| Message ID | 20190511072049.2w7pp723iszp3gra@localhost.localdomain |
|---|---|
| State | New |
| Headers | show |
| Series | pldd.1: Document glibc's unbreakage of tool. | expand |
* G. Branden Robinson: > .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. I'm not sure if it makes sense to document this in the manual page. I expect that the fix will propagate to affected distributions fairly quickly, now that it is available upstream. It's certainly more likely that users will receive a glibc update with the fix than a manpage update with this change. Thanks, Florian
Hi Florian! Response inline. At 2019-05-13T11:48:19+0200, Florian Weimer wrote: > * G. Branden Robinson: > > > .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. > > I'm not sure if it makes sense to document this in the manual page. It might not; another resonable approach might be to nuke the "Bugs" section of the man page entirely. However, see below. > I expect that the fix will propagate to affected distributions fairly > quickly, now that it is available upstream. True for fast-moving distributions; as I noted in the commit message, Debian 10 has already got it backported to its glibc 2.29. > It's certainly more likely that users will receive a glibc update with > the fix than a manpage update with this change. Desktop systems will get both; stripped-down systems will likely follow your scenario. On the other hand I generally read man pages on my full-blown {desk,lap}top, not some embedded or target system. So I can imagine a scenario where somebody is targeting a "stable" or legacy system with glibc 2.29 or older and is wondering why the F "pldd" doesn't work. They type "man pldd" (as a last resort, of course) on their dev box, and lo and behold, all is explained. Michael K. is pretty diligent about having man-pages track behavior changes as they come and go in the Linux kernel, and my patch is an attempt to match that tradition. However, it might not make sense or be his preference for the glibc-related man pages. My primary concern is to get what is now a false statement corrected or removed. pldd is not still broken. I have an update for the fiddly third patch, but once Michael follows up I'll continue that branch of the thread on linux-man only; I'm confident libc-alpha does not care about the fine details of *roff markup. Regards, Branden
Am 13.05.2019 11:48, schrieb Florian Weimer: > * G. Branden Robinson: > >> .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. > > I'm not sure if it makes sense to document this in the manual page. I > expect that the fix will propagate to affected distributions fairly > quickly, now that it is available upstream. It's certainly more likely > that users will receive a glibc update with the fix than a manpage > update with this change. > IMHO it should be noted in the BUGS section. You can not rely that you have always the lastest version of libc (at least i do not have) but you may notice a different behavior and it is simply very helpful to have a hint that certain versions are broken. (if someone cares: my problem was with a64l. It suddenly changed behavior ...) just my 2 cents, re, wh
On Fri, 17 May 2019, Carlos O'Donell wrote: > On Fri, May 17, 2019 at 11:51 AM G. Branden Robinson > <g.branden.robinson@gmail.com> wrote: > > What would you prefer? That the man page not document the bug at all? > > Was it a mistake in your view to have added the information about the > > bug to the man page in the first place? > > I think having the glibc upstream version information is useful. Likewise - if a bug is worth documenting there I think it's unavoidable that the version numbers describe when things changed in glibc upstream. What's more of an issue is when the BUGS section gets out of date or the descriptions of the conditions for an issue are misleading. pow(3) is a case in point; it says "On 64-bits" meaning "on systems using the generic implementation" (i.e., it's written from an assumption that x86_64 and i386 are the only architectures and that i386 is the default), and that issue was fixed in 2.28, while the "If x is negative" described there was both i386-specific (not mentioned as such) and fixed in 2.16.
Hi Branden, On 5/11/19 9:20 AM, G. Branden Robinson wrote: > ...plus a patch with some suggested wording fixes. > > ...plus a patch with some suggestions on improving the formatting and > markup. Sorry for the late reply. I actually applied some of your changes a few days back (they're already in Git). You often have good inputs, but your idiosyncratic submission style does make it harder than necessary for me to deal with that input. Please: * One patch per mail * Patches best inline; if you are worried your mailer may break the patch, then both inline and as an attachment. * Your patch 3 does so many things at the same time that it's impossible to apply. Some of the things I agree with. Others not. * Some of your points in patch 3 are really suggestions suggestions for global changes in the manual pages. Obviously, they would need discussion, and shouldn't be done piecemeal, page at a time. I made some of the uncontroversial changes from this patch manually. Thanks, Michael
On 5/17/19 5:56 PM, Carlos O'Donell wrote: > On Fri, May 17, 2019 at 11:51 AM G. Branden Robinson > <g.branden.robinson@gmail.com> wrote: >> What would you prefer? That the man page not document the bug at all? >> Was it a mistake in your view to have added the information about the >> bug to the man page in the first place? > > I think having the glibc upstream version information is useful. And so do I. My compromise in such cases is to write something like: this: BUGS From glibc 2.19 to 2.29, pldd was broken: it just hung when exe‐ cuted. This problem was fixed in glibc 2.30, and the fix has been backported to earlier glibc versions in some distributions. Thanks, Michael
On 7/29/19 3:18 PM, Michael Kerrisk (man-pages) wrote: > On 5/17/19 5:56 PM, Carlos O'Donell wrote: >> On Fri, May 17, 2019 at 11:51 AM G. Branden Robinson >> <g.branden.robinson@gmail.com> wrote: >>> What would you prefer? That the man page not document the bug at all? >>> Was it a mistake in your view to have added the information about the >>> bug to the man page in the first place? >> >> I think having the glibc upstream version information is useful. > > And so do I. My compromise in such cases is to write something like: > this: > > BUGS > From glibc 2.19 to 2.29, pldd was broken: it just hung when exe‐ > cuted. This problem was fixed in glibc 2.30, and the fix has been > backported to earlier glibc versions in some distributions. > > Thanks, Thank you for being accurate and informative.
Hello Joseph, On 5/20/19 6:58 PM, Joseph Myers wrote: > On Fri, 17 May 2019, Carlos O'Donell wrote: > >> On Fri, May 17, 2019 at 11:51 AM G. Branden Robinson >> <g.branden.robinson@gmail.com> wrote: >>> What would you prefer? That the man page not document the bug at all? >>> Was it a mistake in your view to have added the information about the >>> bug to the man page in the first place? >> >> I think having the glibc upstream version information is useful. > > Likewise - if a bug is worth documenting there I think it's unavoidable > that the version numbers describe when things changed in glibc upstream. > > What's more of an issue is when the BUGS section gets out of date or the > descriptions of the conditions for an issue are misleading. pow(3) is a > case in point; it says "On 64-bits" meaning "on systems using the generic > implementation" (i.e., it's written from an assumption that x86_64 and > i386 are the only architectures and that i386 is the default) and that> issue was fixed in 2.28, So should the text now read something like: "Before glibc 2.28, on 64-bit systems [this bug existed]"? > while the "If x is negative" described there was > both i386-specific (not mentioned as such) and fixed in 2.16. And similarly, should the text now read something like: "On i386 systems and glibc versions earlier than 2.16..."? Thanks, Michael
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