[PATCH/RFC 0/6] ld.so.8: some improvements from Debian

[PATCH/RFC 0/6] ld.so.8: some improvements from Debian

[Jonathan Nieder]

Hi,

I would like to see Debian using the ld.so(8) page from the man-pages
project instead of its own custom copy, so people making improvements
to that documentation would not need to choose which to contribute to.
Here are some changes that might make it easier to use the upstream
ld.so.8 as a drop-in replacement.

I have tried to be very conservative, when in doubt matching what is
in Debian's libc-bin package.  Some comments on this in the mails with
each patch.

Anyway, some of these seem to me like good improvements to the page
regardless.  What do you think?

Jonathan Nieder (6):
  ld.so.8: clarify synopsis
  ld.so.8: move important information toward the top
  ld.so.8: document LD_ASSUME_KERNEL
  ld.so.8: document Debian's /etc/ld.so.nohwcap extension
  ld.so.8: document $PLATFORM and $LIB expansion
  ld.so.8: document how hwcaps affect search path

 man8/ld.so.8 |  181 +++++++++++++++++++++++++++++++++++++++++-----------------
 1 files changed, 128 insertions(+), 53 deletions(-)
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/6] ld.so.8: clarify synopsis

[Jonathan Nieder]

The <program> argument to ld-linux.so is not optional.

While clarifying that, list supported options in the synopsis, improve
the typography a little, and move information about how the dynamic
linker is usually used from the SYNOPSIS to the DESCRIPTION section.

Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
Not from Debian --- this is just me nitpicking to make the page look a
little more conventional.

The most iffy aspects of this patch are probably the use of \*(lq (is
it portable enough?) and the inclusion of the --audit option without
a detailed description in the OPTIONS section.  Naturally I like it
anyway. ;-)

 man8/ld.so.8 |   31 ++++++++++++++++++++++---------
 1 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index 84278d0..f0718dd 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -3,22 +3,35 @@
 .SH NAME
 ld.so, ld-linux.so* \- dynamic linker/loader
 .SH SYNOPSIS
+.B /lib/ld-linux.so.*
+.RB [ \-\-list ]
+.RB [ \-\-verify ]
+.RB [ \-\-library-path
+.IR paths ]
+.RB [ \-\-inhibit-rpath
+.IR objects ]
+.RB [ \-\-audit
+.IR auditors ]
+.I program
+.RI [ arg ...]
+.SH DESCRIPTION
+The programs
+.B ld.so
+and
+.B ld-linux.so*
+find and load the shared libraries needed by a program, prepare
+the program to run, and then run it.
+.LP
 The dynamic linker can be run either indirectly by running some
 dynamically linked program or library (in which case no command-line options
 to the dynamic linker can be passed and, in the ELF case, the dynamic linker
 which is stored in the
 .B .interp
-section of the program is executed) or directly by running:
-.P
-.I /lib/ld-linux.so.*
-[OPTIONS] [PROGRAM [ARGUMENTS]]
-.SH DESCRIPTION
-The programs
-.B ld.so
-and
-.B ld-linux.so*
-find and load the shared libraries needed by a program, prepare
-the program to run, and then run it.
+section of the program is executed) or directly by running
+.RB \*(lq /lib/ld-linux.so.*
+.RI [ options ]
+.I program
+.RI [ arguments ]\*(rq.
 .LP
 Linux binaries require dynamic linking (linking at run time)
 unless the
-- 
1.7.7

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/6] ld.so.8: move important information toward the top

[Jonathan Nieder]

The novice might wonder why programs need linking at run-time at all,
so point out early on that the purpose of this exercise is linking
against shared libraries that can be upgraded independently of the
applications that use them (as contrasted with static linking).
Wording taken from the Debian glibc package, 2003.

Most readers today won't care about /lib/ld.so and a.out binaries, so
move the passage describing that to the end of the description
section.  This way, it is more likely that the juicy bits (the
overview and the library search path) will fit on the first page.

Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
 man8/ld.so.8 |   39 +++++++++++++++++++--------------------
 1 files changed, 19 insertions(+), 20 deletions(-)

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index f0718dd..9fc96c9 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -21,6 +21,12 @@ and
 .B ld-linux.so*
 find and load the shared libraries needed by a program, prepare
 the program to run, and then run it.
+Unless the
+.B \-static
+option was given to
+.BR ld (1)
+during compilation, all Linux programs are incomplete and require
+further linking at run time.
 .LP
 The dynamic linker can be run either indirectly by running some
 dynamically linked program or library (in which case no command-line options
@@ -33,26 +39,6 @@ section of the program is executed) or directly by running
 .I program
 .RI [ arguments ]\*(rq.
 .LP
-Linux binaries require dynamic linking (linking at run time)
-unless the
-.B \-static
-option was given to
-.BR ld (1)
-during compilation.
-.LP
-The program
-.B ld.so
-handles a.out binaries, a format used long ago;
-.B ld-linux.so*
-handles ELF (\fI/lib/ld-linux.so.1\fP for libc5, \fI/lib/ld-linux.so.2\fP
-for glibc2), which everybody has been using for years now.
-Otherwise both have the same behavior, and use the same
-support files and programs
-.BR ldd (1),
-.BR ldconfig (8)
-and
-.IR /etc/ld.so.conf .
-.LP
 The shared libraries needed by the program are searched for
 in the following order:
 .IP o 3
@@ -85,6 +71,19 @@ and then
 If the binary was linked with the
 .B \-z nodeflib
 linker option, this step is skipped.
+.LP
+The program
+.B ld.so
+handles a.out binaries, a format used long ago;
+.B ld-linux.so*
+handles ELF (\fI/lib/ld-linux.so.1\fP for libc5, \fI/lib/ld-linux.so.2\fP
+for glibc2), which everybody has been using for years now.
+Otherwise both have the same behavior, and use the same
+support files and programs
+.BR ldd (1),
+.BR ldconfig (8)
+and
+.IR /etc/ld.so.conf .
 .SS $ORIGIN and rpath
 .PP
 .B ld.so
-- 
1.7.7

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 3/6] ld.so.8: document LD_ASSUME_KERNEL

[Jonathan Nieder]

From Aurelian Jarno's update to the Debian glibc package, r1812
(ld.so.8: Update the manpage, 2006-10-01).  Presumably the text is
originally from the Red Hat document "What is LD_ASSUME_KERNEL and
what does it affect?", by Eric Paris and copyright © Red Hat Inc,
2004.
---
Eric, is it ok to include this text in the (public domain) ld.so.8
manpage?

To be safe, I'm withholding my sign-off for now, but I'm hoping it
should be ok.

 man8/ld.so.8 |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index 9fc96c9..6b5799b 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -190,6 +190,18 @@ for a.out binaries only.
 Old versions of ld\-linux.so.1 also supported
 .BR LD_ELF_PRELOAD .
 .TP
+.B LD_ASSUME_KERNEL
+(glibc since 2.2.3)
+Every DSO (Dynamic Shared Object, aka shared library) can tell the dynamic linker in glibc which
+minimum OS ABI version is needed. The information about the minimum OS ABI version is encoded in
+a ELF note section usually named .note.ABI-tag. This is used to determine which library to load
+when multiple version of the same library is installed on the system.
+
+The
+.B LD_ASSUME_KERNEL
+environment variable overrides the kernel version used by the dynamic linker to determine which
+library to load.
+.TP
 .B LD_AUDIT
 (glibc since 2.4)
 A colon-separated list of user-specified, ELF shared objects
-- 
1.7.7

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 4/6] ld.so.8: document Debian's /etc/ld.so.nohwcap extension

[Jonathan Nieder]

To avoid trouble when the generic version of libc has been upgraded
but some machine-specific versions have not, Ben Collins came up with
this hack to temporarily disable the feature of choosing which library
to load based on hardware capabilities.  It is just an internal
feature, but let's document it anyway to avoid people being confused
if Debian's custom ld.so(8) manpage gets replaced with an up-to-date
copy from man-pages.

Text from Aurelian Jarno's update to the Debian glibc package, r1812
(ld.so.8: Update the manpage, 2006-10-01).

Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
Incidentally, is there some upstream-supported way to do this
(override LD_HWCAP_MASK using a file on the filesystem)?  How do other
distros address this problem (e.g., ABI mismatches between out-of-date
hwcap libs and the updated libnss) during upgrades?

 man8/ld.so.8 |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index 6b5799b..a5ecc4b 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -382,6 +382,11 @@ libraries and an ordered list of candidate libraries.
 File containing a whitespace separated list of ELF shared libraries to
 be loaded before the program.
 .TP
+.I /etc/ld.so.nohwcap
+(Debian only, since glibc 2.2.93-1)
+When this file is present the dynamic linker will load the non-optimized version
+of a library, even if the CPU supports the optimized version.
+.TP
 .B lib*.so*
 shared libraries
 .PD
-- 
1.7.7

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 5/6] ld.so.8: document $PLATFORM and $LIB expansion

[Jonathan Nieder]

Wording based on a combination of a patch by Aurelien Jarno,
2007-11-18 (Debian glibc r2686) and comments by Michael Kerrisk
from man-pages-2.55~65 (Document $ORIGIN and rpath, 2007-05-26).

Fixes http://bugs.debian.org/444145

Requested-by: Reinhard Tartler <siretart-8fiUuRrzOP0dnm+yROfE0A@public.gmane.org>
Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
 man8/ld.so.8 |   78 ++++++++++++++++++++++++++++++++++-----------------------
 1 files changed, 46 insertions(+), 32 deletions(-)

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index a5ecc4b..409876d 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -84,8 +84,28 @@ support files and programs
 .BR ldconfig (8)
 and
 .IR /etc/ld.so.conf .
-.SS $ORIGIN and rpath
-.PP
+.SH OPTIONS
+.TP
+.B \-\-list
+List all dependencies and how they are resolved.
+.TP
+.B \-\-verify
+Verify that program is dynamically linked and this dynamic linker can handle
+it.
+.TP
+.B \-\-library\-path PATH
+Override
+.B LD_LIBRARY_PATH
+environment variable setting (see below).
+.TP
+.B \-\-inhibit\-rpath LIST
+Ignore RPATH and RUNPATH information in object names in LIST.
+This option is ignored if
+.B ld.so
+is set-user-ID or set-group-ID.
+.SH RPATH TOKEN EXPANSION
+.TP
+.B ORIGIN
 .B ld.so
 understands the string
 .I $ORIGIN
@@ -106,38 +126,32 @@ This facilitates the creation of "turn-key" applications that
 do not need to be installed into special directories,
 but can instead be unpacked into any directory
 and still find their own shared libraries.
-.\" ld.so also understands $LIB, with the same meaning as $ORIGIN/lib,
-.\" it appears.
-.\"
-.\" There is also $PLATFORM.  This is a kind of wildcard
-.\" of directories related at AT_HWCAP.  To get an idea of the
-.\" places that $PLATFORM would match, look at the output of the
-.\" following:
-.\"
-.\" mkdir /tmp/d
-.\" LD_LIBRARY_PATH=/tmp/d strace -e open /bin/date 2>&1 | grep /tmp/d
-.\"
+.TP
+.B PLATFORM
+The string \fB$PLATFORM\fR (or equivalently \fB${PLATFORM}\fR) expands to
+the processor type of the current machine.
+This information is obtained from the kernel via the AT_HWCAP entry
+in the ELF aux vector.
+Please note that on some architectures the Linux kernel doesn't provide
+a platform string to the dynamic linker.
+
+To get an idea of the places that \fB$PLATFORM\fR would match,
+look at the output of the following:
+.in +4n
+.nf
+
+mkdir /tmp/d
+LD_LIBRARY_PATH=/tmp/d strace -e open /bin/date 2>&1 | grep /tmp/d
+
+.fi
+.in
+.TP
+.B LIB
+The string \fB$LIB\fR (or equivalently \fB${LIB}\fR) represents
+the system libraries directory, which is /lib for the native architecture
+on FHS compliant GNU/Linux systems.
 .\" ld.so lets names be abbreviated, so $O will work for $ORIGIN;
 .\" Don't do this!!
-.SH OPTIONS
-.TP
-.B \-\-list
-List all dependencies and how they are resolved.
-.TP
-.B \-\-verify
-Verify that program is dynamically linked and this dynamic linker can handle
-it.
-.TP
-.B \-\-library\-path PATH
-Override
-.B LD_LIBRARY_PATH
-environment variable setting (see below).
-.TP
-.B \-\-inhibit\-rpath LIST
-Ignore RPATH and RUNPATH information in object names in LIST.
-This option is ignored if
-.B ld.so
-is set-user-ID or set-group-ID.
 .SH ENVIRONMENT
 There are four important environment variables.
 .TP
-- 
1.7.7

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 6/6] ld.so.8: document how hwcaps affect search path

[Jonathan Nieder]

Wording by Aurelien Jarno, from Debian glibc's r4701 (2011-06-04).

Fixes http://bugs.debian.org/622385

Requested-by: Reuben Thomas <rrt-0NV8xZLkR+A@public.gmane.org>
Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
I think this information belongs in the ldconfig(8) page, not
ld.so(8), but either one is better than nowhere. ;-)

That's the end of the series.  Thanks for reading.

 man8/ld.so.8 |   32 ++++++++++++++++++++++++++++++++
 1 files changed, 32 insertions(+), 0 deletions(-)

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index 409876d..13b5508 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -63,6 +63,8 @@ in the augmented library path.
 If, however, the binary was linked with the
 .B \-z nodeflib
 linker option, libraries in the default library paths are skipped.
+Libraries installed in hardware capabilities directories (see below)
+are preferred to other libraries.
 .IP o
 In the default path
 .IR /lib ,
@@ -152,6 +154,36 @@ the system libraries directory, which is /lib for the native architecture
 on FHS compliant GNU/Linux systems.
 .\" ld.so lets names be abbreviated, so $O will work for $ORIGIN;
 .\" Don't do this!!
+.SH HARDWARE CAPABILITIES
+Libraries might be compiled using hardware-specific instructions which do not
+exist on every CPU. Such libraries should be installed in directories whose name
+defines the hardware capabilities such as \fB/usr/lib/sse2/\fR. The dynamic
+linker checks these directories against the hardware of the machine and selects
+the best suitable version of a given library. Hardware capabilities directories
+could be cascaded to combine CPU features. Hardware capabilities depends on
+the CPU. The following names are currently recognized:
+.B Alpha
+ev4, ev5, ev56, ev6, ev67
+.TP
+.B MIPS
+loongson2e, loongson2f, octeon, octeon2
+.TP
+.B PowerPC
+4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle,
+fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601,
+ppc64, smt, spe, ucache, vsx
+.TP
+.B SPARC
+flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
+.TP
+.B s390
+dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle,
+z900, z990, z9-109, z10, zarch
+.TP
+.TP
+.B x86 (32-bit only)
+acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx,
+mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm
 .SH ENVIRONMENT
 There are four important environment variables.
 .TP
-- 
1.7.7

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/6] ld.so.8: clarify synopsis

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 259 bytes --]

On Thursday 20 October 2011 03:04:12 Jonathan Nieder wrote:
> +.RB \*(lq /lib/ld-linux.so.*
> +.RI [ options ]
> +.I program
> +.RI [ arguments ]\*(rq.

can we avoid lq/rq ?  it's pretty uncommon and imo, just useless noise.

the rest looks fine to me.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 4/6] ld.so.8: document Debian's /etc/ld.so.nohwcap extension

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 558 bytes --]

On Thursday 20 October 2011 03:14:24 Jonathan Nieder wrote:
> Incidentally, is there some upstream-supported way to do this
> (override LD_HWCAP_MASK using a file on the filesystem)?  How do other
> distros address this problem (e.g., ABI mismatches between out-of-date
> hwcap libs and the updated libnss) during upgrades?

use IFUNC and then there's usually no need for hwcap alternatives

> --- a/man8/ld.so.8
> +++ b/man8/ld.so.8
>
> +.I /etc/ld.so.nohwcap
> +(Debian only, since glibc 2.2.93-1)

i think this belongs in Debian's man-page patchset
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 5/6] ld.so.8: document $PLATFORM and $LIB expansion

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 571 bytes --]

On Thursday 20 October 2011 03:15:38 Jonathan Nieder wrote:
> +.B LIB
> +The string \fB$LIB\fR (or equivalently \fB${LIB}\fR) represents
> +the system libraries directory, which is /lib for the native architecture
> +on FHS compliant GNU/Linux systems.

a better description might be something like "$LIB expands to the short libdir 
name that glibc was configured to install into".  and then refer to it usually 
being "/lib" for the native ABI (not architecture) on FHS compliant Linux 
systems.  man-pages does not use the "GNU/" noise qualification.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 1/6] ld.so.8: clarify synopsis

[Reuben Thomas]

On 20 October 2011 13:08, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> On Thursday 20 October 2011 03:04:12 Jonathan Nieder wrote:
>> +.RB \*(lq /lib/ld-linux.so.*
>> +.RI [ options ]
>> +.I program
>> +.RI [ arguments ]\*(rq.
>
> can we avoid lq/rq ?  it's pretty uncommon and imo, just useless noise.

Au contraire, proper quotation marks make man pages more readable; to
be encouraged.

-- 
http://rrt.sc3d.org
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/6] ld.so.8: clarify synopsis

[Reuben Thomas]

On 20 October 2011 13:17, Reuben Thomas <rrt-0NV8xZLkR+A@public.gmane.org> wrote:
> On 20 October 2011 13:08, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
>> On Thursday 20 October 2011 03:04:12 Jonathan Nieder wrote:
>>> +.RB \*(lq /lib/ld-linux.so.*
>>> +.RI [ options ]
>>> +.I program
>>> +.RI [ arguments ]\*(rq.
>>
>> can we avoid lq/rq ?  it's pretty uncommon and imo, just useless noise.
>
> Au contraire, proper quotation marks make man pages more readable; to
> be encouraged.

I'm sorry, I retract that, quotation marks are clearly not needed in
that context. Apologies for the noise.

-- 
http://rrt.sc3d.org
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/6] ld.so.8: clarify synopsis

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 578 bytes --]

On Thursday 20 October 2011 14:17:39 Reuben Thomas wrote:
> On 20 October 2011 13:08, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> > On Thursday 20 October 2011 03:04:12 Jonathan Nieder wrote:
> >> +.RB \*(lq /lib/ld-linux.so.*
> >> +.RI [ options ]
> >> +.I program
> >> +.RI [ arguments ]\*(rq.
> > 
> > can we avoid lq/rq ?  it's pretty uncommon and imo, just useless noise.
> 
> Au contraire, proper quotation marks make man pages more readable; to
> be encouraged.

sorry, my point was lq/rq vs "", not lq/rq vs nothing ...
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 1/6] ld.so.8: clarify synopsis

[Reuben Thomas]

On 20 October 2011 13:26, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> On Thursday 20 October 2011 14:17:39 Reuben Thomas wrote:
>> On 20 October 2011 13:08, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
>> > On Thursday 20 October 2011 03:04:12 Jonathan Nieder wrote:
>> >> +.RB \*(lq /lib/ld-linux.so.*
>> >> +.RI [ options ]
>> >> +.I program
>> >> +.RI [ arguments ]\*(rq.
>> >
>> > can we avoid lq/rq ?  it's pretty uncommon and imo, just useless noise.
>>
>> Au contraire, proper quotation marks make man pages more readable; to
>> be encouraged.
>
> sorry, my point was lq/rq vs "", not lq/rq vs nothing ...

In that case I retract my retraction: I'd much rather have curly
quotes. They're more readable and they make it easier to tell when
quotes are part of input/output (in which case they're straight).

-- 
http://rrt.sc3d.org
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/6] ld.so.8: clarify synopsis

[Jonathan Nieder]

Mike Frysinger wrote:
> On Thursday 20 October 2011 03:04:12 Jonathan Nieder wrote:

>> +.RB \*(lq /lib/ld-linux.so.*
>> +.RI [ options ]
>> +.I program
>> +.RI [ arguments ]\*(rq.
>
> can we avoid lq/rq ?

Sorry about that.  I couldn't figure out how to get a literal
quotation mark in there, but more to the point, it would have
been better to just say something like

	.B /lib/ld-linux.so.*
	or
	.BR /lib64/ld-linux-x86-64.so.2 .

here.

So, um, yes we can avoid the nonportable quote mark style, and
it even would make the page a little better.

I'll reroll once reviewing v1 stops seeming fruitful.

> the rest looks fine to me.

Thanks for looking it over.  
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/6] ld.so.8: clarify synopsis

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 1192 bytes --]

On Thursday 20 October 2011 14:28:39 Reuben Thomas wrote:
> On 20 October 2011 13:26, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> > On Thursday 20 October 2011 14:17:39 Reuben Thomas wrote:
> >> On 20 October 2011 13:08, Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org> wrote:
> >> > On Thursday 20 October 2011 03:04:12 Jonathan Nieder wrote:
> >> >> +.RB \*(lq /lib/ld-linux.so.*
> >> >> +.RI [ options ]
> >> >> +.I program
> >> >> +.RI [ arguments ]\*(rq.
> >> > 
> >> > can we avoid lq/rq ?  it's pretty uncommon and imo, just useless
> >> > noise.
> >> 
> >> Au contraire, proper quotation marks make man pages more readable; to
> >> be encouraged.
> > 
> > sorry, my point was lq/rq vs "", not lq/rq vs nothing ...
> 
> In that case I retract my retraction: I'd much rather have curly
> quotes. They're more readable and they make it easier to tell when
> quotes are part of input/output (in which case they're straight).

it's uncommon in the man-pages tree.  if you want to start a discussion about 
the style in the tree, then feel free, but please don't introduce deviation.  
do it right from the start.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 5/6] ld.so.8: document $PLATFORM and $LIB expansion

[Jonathan Nieder]

(-cc: pasky, since I had his address wrong.  Goodbye, suse addresses.)
Mike Frysinger wrote:
> On Thursday 20 October 2011 03:15:38 Jonathan Nieder wrote:

>> +.B LIB
>> +The string \fB$LIB\fR (or equivalently \fB${LIB}\fR) represents
>> +the system libraries directory, which is /lib for the native architecture
>> +on FHS compliant GNU/Linux systems.
>
> a better description might be something like "$LIB expands to the short libdir 
> name that glibc was configured to install into". and then refer to it usually 
> being "/lib" for the native ABI (not architecture) on FHS compliant Linux 
> systems.  man-pages does not use the "GNU/" noise qualification.

Right, it's $(slibdir), which goes in configparms since autoconf is
not wired to handle the /usr/lib vs /lib distinction.  The FHS
describes the contents of /lib as "Essential shared libraries and
kernel modules".

I guess it should say:

	$LIB expands to the path to the "essential shared libraries"
	directory, which is /lib for the native ABI on FHS compliant
	systems.

The FHS is supposed to apply to non-Linux Unix systems too, anyway.

But that leaves me with questions:

 - what is $LIB for a non-native ABI?

 - does anyone customize this to point somewhere else and make their
   machine non-FHS-compliant?  Maybe NixOS and Gentoo Prefix do.
   What would a person typically use ${LIB} in an rpath for?
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 4/6] ld.so.8: document Debian's /etc/ld.so.nohwcap extension

[Jonathan Nieder]

Mike Frysinger wrote:

> use IFUNC and then there's usually no need for hwcap alternatives

I see.  (I'm not sure that's always true yet for optimizations GCC
knows about, but it's certainly a good direction to go in.)

> On Thursday 20 October 2011 03:14:24 Jonathan Nieder wrote:

>> --- a/man8/ld.so.8
>> +++ b/man8/ld.so.8
>>
>> +.I /etc/ld.so.nohwcap
>> +(Debian only, since glibc 2.2.93-1)
>
> i think this belongs in Debian's man-page patchset

Fair enough.  Let's drop it from this series, and I can ask joey
whether he thinks it's worth documenting when proposing installing
these pages in Debian manpages.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC 0/6] ld.so.8: some improvements from Debian

[Reuben Thomas]

Sorry I took so long to get around to reviewing this. Some comments:

-       /lib/ld-linux.so.*  [OPTIONS] [PROGRAM [ARGUMENTS]]
+       /lib/ld-linux.so.*  [--list] [--verify] [--library-path
+       paths] [--inhibit-rpath objects] [--audit auditors] program
+       [arg...]

Unless the options to a program are very short, I don't like to see
them all listed in a synopsis, as it's too long-winded.

Also, I prefer upper-case for metasyntactic variables in man pages. So
in fact, the original is fine, though I do like ellipsis to indicate
multiple arguments, so:

-       /lib/ld-linux.so.*  [OPTIONS] [PROGRAM [ARGUMENTS]]
+       /lib/ld-linux.so.*  [OPTION...] [PROGRAM [ARGUMENT...]]

I don't think the phrase '"turn-key"' is helpful here; I'd remove it.

+       hardware capabilities such as /usr/lib/sse2/. The dynamic

Insert comma after "hardware capabilities".

+       CPU. The following names are currently recognized: Alpha ev4,
+       ev5, ev56, ev6, ev67

Insert para break before "Alpha".

+              multiple version of the same library is

version → versions

-- 
http://rrt.sc3d.org
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 5/6] ld.so.8: document $PLATFORM and $LIB expansion

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 1551 bytes --]

On Friday 21 October 2011 01:25:28 Jonathan Nieder wrote:
>  - what is $LIB for a non-native ABI?

whatever it's been configured for.  it isn't an env var that is the same across 
all ABIs.  you could configure every ABI to use /lib, but that'd be dumb.

if we look at the 3 ABI's we have on the x86 system and their standard install 
paths:
	- 32bit: lives in /lib and has ldso at /lib/ld-linux.so.2
	- 64bit: lives in /lib64 and has ldso at /lib64/ld-linux-x86-64.so.2
	- x32: lives in /libx32 and has ldso at /libx32/ld-linux-x32.so.2

you don't `./configure && make` once to get multiple ABIs.  you have to 
manually run that per ABI.  so the 32bit ABI gets configured so $LIB is set to 
/lib, then the 64bit ABI gets configured for /lib64, etc...

the ldso at runtime will replace $LIB with whatever it was configured for

>  - does anyone customize this to point somewhere else and make their
>    machine non-FHS-compliant?  Maybe NixOS and Gentoo Prefix do.

you can't really consider Gentoo Prefix as a being the domain of FHS rule.  it 
is not a distro you boot ... it's a set of packages you build/install into 
your $HOME because your host system is old/broken/whatever.

>    What would a person typically use ${LIB} in an rpath for?

it's useful when you want to preload a library for multiple process types.  
why this would get used in an RPATH tag, i can't really guess since the ELF 
itself is already configured for a specific ABI.  maybe someone more inventive 
can come up with something ;).
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH/RFC 0/6] ld.so.8: some improvements from Debian

[Michael Kerrisk (man-pages)]

Jonathan,

This patch series fell on the floor. Are you interested in having
another go? If yes, let's discuss some details first.

Cheers,

Michael


On Thu, Oct 20, 2011 at 8:01 PM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hi,
>
> I would like to see Debian using the ld.so(8) page from the man-pages
> project instead of its own custom copy, so people making improvements
> to that documentation would not need to choose which to contribute to.
> Here are some changes that might make it easier to use the upstream
> ld.so.8 as a drop-in replacement.
>
> I have tried to be very conservative, when in doubt matching what is
> in Debian's libc-bin package.  Some comments on this in the mails with
> each patch.
>
> Anyway, some of these seem to me like good improvements to the page
> regardless.  What do you think?
>
> Jonathan Nieder (6):
>  ld.so.8: clarify synopsis
>  ld.so.8: move important information toward the top
>  ld.so.8: document LD_ASSUME_KERNEL
>  ld.so.8: document Debian's /etc/ld.so.nohwcap extension
>  ld.so.8: document $PLATFORM and $LIB expansion
>  ld.so.8: document how hwcaps affect search path
>
>  man8/ld.so.8 |  181 +++++++++++++++++++++++++++++++++++++++++-----------------
>  1 files changed, 128 insertions(+), 53 deletions(-)
> --
> To unsubscribe from this list: send the line "unsubscribe linux-man" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC 0/6] ld.so.8: some improvements from Debian

[Jonathan Nieder]

Michael Kerrisk (man-pages) wrote:

> This patch series fell on the floor. Are you interested in having
> another go? If yes, let's discuss some details first.

Yeah, I'd be happy to revisit this and get it done.  Sorry for letting
it stall.

Thanks,
Jonathan
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 5/6] ld.so.8: document $PLATFORM and $LIB expansion

[Jonathan Nieder]

Mike Frysinger wrote:
> On Friday 21 October 2011 01:25:28 Jonathan Nieder wrote:

>>    What would a person typically use ${LIB} in an rpath for?
>
> it's useful when you want to preload a library for multiple process types.  
> why this would get used in an RPATH tag, i can't really guess

Ah, that makes sense.  So it's for consistency with LD_LIBRARY_PATH
and LD_PRELOAD.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC 0/6] ld.so.8: some improvements from Debian

[Michael Kerrisk (man-pages)]

On Tue, Apr 17, 2012 at 4:58 AM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Michael Kerrisk (man-pages) wrote:
>
>> This patch series fell on the floor. Are you interested in having
>> another go? If yes, let's discuss some details first.
>
> Yeah, I'd be happy to revisit this and get it done.  Sorry for letting
> it stall.

Could you possibly also rearchitect the patch series please, in the
light of the following:
* There have been a (very) few changes to upstream ld.so.8, so you'll
need to rebase.
* Please clearly separate out those pieces that simply bridge the gap
between upstream ld.so.8 and Debian ld.so.8 and those pieces that are
your own enhancements. (I did correctly understand that there are some
of those, right?).

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC 0/6] ld.so.8: some improvements from Debian

[Jonathan Nieder]

Michael Kerrisk (man-pages) wrote:

> Could you possibly also rearchitect the patch series please, in the
> light of the following:
> * There have been a (very) few changes to upstream ld.so.8, so you'll
> need to rebase.

Sure, no problem.

> * Please clearly separate out those pieces that simply bridge the gap
> between upstream ld.so.8 and Debian ld.so.8 and those pieces that are
> your own enhancements. (I did correctly understand that there are some
> of those, right?).

Do I understand correctly that you want first a patch that makes it look
just like Debian's ld.so.8, and after that patches that make it more
palatable?  That doesn't seem quite right to me --- for example, it would
mean first reverting the changes to upstream ld.so.8 and then reapplying
them again.

Jonathan
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC 0/6] ld.so.8: some improvements from Debian

[Michael Kerrisk (man-pages)]

[Correcting my correction to Petr's address]

Hi Jonathan,

On Tue, Apr 17, 2012 at 5:24 AM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Michael Kerrisk (man-pages) wrote:
>
>> Could you possibly also rearchitect the patch series please, in the
>> light of the following:
>> * There have been a (very) few changes to upstream ld.so.8, so you'll
>> need to rebase.
>
> Sure, no problem.
>
>> * Please clearly separate out those pieces that simply bridge the gap
>> between upstream ld.so.8 and Debian ld.so.8 and those pieces that are
>> your own enhancements. (I did correctly understand that there are some
>> of those, right?).
>
> Do I understand correctly that you want first a patch that makes it look
> just like Debian's ld.so.8, and after that patches that make it more
> palatable?  That doesn't seem quite right to me --- for example, it would
> mean first reverting the changes to upstream ld.so.8 and then reapplying
> them again.

IIUC, your purpose is to allow Debian to drop downstream ld.so.8, by
ensuring that upstream ld.so.8 has everything that useful from the
downstream (purpose 1). Along the way, you also saw places where the
upstream page could be further improved with *new* material (purpose
2). Right? What I'm saying is, please keep a good separation between
those two purposes in your patch. Simplest would be a series of
patches that dealt with purpose 1, followed by another series for
purpose 2. Does that make sense?

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH/RFC 0/6] ld.so.8: some improvements from Debian

[Jonathan Nieder]

Michael Kerrisk (man-pages) wrote:

> IIUC, your purpose is to allow Debian to drop downstream ld.so.8, by
> ensuring that upstream ld.so.8 has everything that useful from the
> downstream (purpose 1). Along the way, you also saw places where the
> upstream page could be further improved with *new* material (purpose
> 2). Right? What I'm saying is, please keep a good separation between
> those two purposes in your patch. Simplest would be a series of
> patches that dealt with purpose 1, followed by another series for
> purpose 2. Does that make sense?

Yeah, that makes more sense.  I don't remember the details any more,
but my intent was always only purpose #1.  I do remember there being
places where Debian and upstream differed and both seemed wrong, where
I went my own way.

Anyway, I will definitely try to follow the guideline you have
suggested above.  Thanks for your help.

Jonathan
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2] ld.so.8: Document effect of hwcaps on search path

[Jonathan Nieder]

Wording by Aurelien Jarno from Debian glibc's r4701 (2011-06-04).

Addresses http://bugs.debian.org/622385

Requested-by: Reuben Thomas <rrt-0NV8xZLkR+A@public.gmane.org>
Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
Michael Kerrisk (man-pages) wrote:

> IIUC, your purpose is to allow Debian to drop downstream ld.so.8, by
> ensuring that upstream ld.so.8 has everything that useful from the
> downstream (purpose 1).

Let's just handle them as isolated patches.  This one comes from
Debian and the text matches what I get with "man ld.so" on a Debian
system.  Since v1, I have rebased it against "master" and rewrapped to
use 76-character instead of 80-character lines.

 man8/ld.so.8 |   33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index 2fbacae0..c0084376 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -64,6 +64,8 @@ in the augmented library path.
 If, however, the binary was linked with the
 .B \-z nodeflib
 linker option, libraries in the default library paths are skipped.
+Libraries installed in hardware capabilities directories (see below)
+are preferred to other libraries.
 .IP o
 In the default path
 .IR /lib ,
@@ -129,6 +131,37 @@ is set-user-ID or set-group-ID.
 .TP
 .B \-\-audit LIST
 Use objects named in LIST as auditors.
+.SH HARDWARE CAPABILITIES
+Libraries might be compiled using hardware-specific instructions which do
+not exist on every CPU. Such libraries should be installed in directories
+whose name defines the hardware capabilities such as \fB/usr/lib/sse2/\fR.
+The dynamic linker checks these directories against the hardware of the
+machine and selects the best suitable version of a given library. Hardware
+capabilities directories could be cascaded to combine CPU features. Hardware
+capabilities depends on the CPU. The following names are currently
+recognized:
+.B Alpha
+ev4, ev5, ev56, ev6, ev67
+.TP
+.B MIPS
+loongson2e, loongson2f, octeon, octeon2
+.TP
+.B PowerPC
+4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle,
+fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601,
+ppc64, smt, spe, ucache, vsx
+.TP
+.B SPARC
+flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
+.TP
+.B s390
+dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle,
+z900, z990, z9-109, z10, zarch
+.TP
+.TP
+.B x86 (32-bit only)
+acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx,
+mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm
 .SH ENVIRONMENT
 There are four important environment variables.
 .TP
-- 
1.7.10

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] ld.so.8: Document effect of hwcaps on search path

[Michael Kerrisk (man-pages)]

Jonathan,

On Tue, Apr 17, 2012 at 7:03 AM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Wording by Aurelien Jarno from Debian glibc's r4701 (2011-06-04).
>
> Addresses http://bugs.debian.org/622385
>
> Requested-by: Reuben Thomas <rrt-0NV8xZLkR+A@public.gmane.org>
> Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> ---
> Michael Kerrisk (man-pages) wrote:
>
>> IIUC, your purpose is to allow Debian to drop downstream ld.so.8, by
>> ensuring that upstream ld.so.8 has everything that useful from the
>> downstream (purpose 1).
>
> Let's just handle them as isolated patches.  This one comes from
> Debian and the text matches what I get with "man ld.so" on a Debian
> system.  Since v1, I have rebased it against "master" and rewrapped to
> use 76-character instead of 80-character lines.

Some minor formatting points:
* Please start new sentences on new lines.
* I strongly prefer the forms .B, .I, etc. over \fB...\fP, etc. Also,
the particular case here if a pathname should be formatted italic.

Could you please tweak as above and resend.

See also comments below.

>
>  man8/ld.so.8 |   33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
>
> diff --git a/man8/ld.so.8 b/man8/ld.so.8
> index 2fbacae0..c0084376 100644
> --- a/man8/ld.so.8
> +++ b/man8/ld.so.8
> @@ -64,6 +64,8 @@ in the augmented library path.
>  If, however, the binary was linked with the
>  .B \-z nodeflib
>  linker option, libraries in the default library paths are skipped.
> +Libraries installed in hardware capabilities directories (see below)
> +are preferred to other libraries.
>  .IP o
>  In the default path
>  .IR /lib ,
> @@ -129,6 +131,37 @@ is set-user-ID or set-group-ID.
>  .TP
>  .B \-\-audit LIST
>  Use objects named in LIST as auditors.
> +.SH HARDWARE CAPABILITIES
> +Libraries might be compiled using hardware-specific instructions which do
> +not exist on every CPU. Such libraries should be installed in directories
> +whose name defines the hardware capabilities such as \fB/usr/lib/sse2/\fR.

name defines ==> names define

> +The dynamic linker checks these directories against the hardware of the
> +machine and selects the best suitable version of a given library. Hardware

best suitable ==> most suitable

> +capabilities directories could be cascaded to combine CPU features. Hardware

"could be"? Should this be "can be"?

> +capabilities depends on the CPU. The following names are currently

depends ==> depend

> +recognized:
> +.B Alpha
> +ev4, ev5, ev56, ev6, ev67
> +.TP
> +.B MIPS
> +loongson2e, loongson2f, octeon, octeon2
> +.TP
> +.B PowerPC
> +4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle,
> +fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601,
> +ppc64, smt, spe, ucache, vsx
> +.TP
> +.B SPARC
> +flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
> +.TP
> +.B s390
> +dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle,
> +z900, z990, z9-109, z10, zarch
> +.TP
> +.TP
> +.B x86 (32-bit only)
> +acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx,
> +mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm
>  .SH ENVIRONMENT
>  There are four important environment variables.
>  .TP
> --
> 1.7.10
>

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3] ld.so.8: Document effect of hwcaps on search path

[Jonathan Nieder]

Wording by Aurelien Jarno from Debian glibc's r4701 (2011-06-04).

Addresses http://bugs.debian.org/622385

Requested-by: Reuben Thomas <rrt-0NV8xZLkR+A@public.gmane.org>
Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
---
Michael Kerrisk (man-pages) wrote:

> Some minor formatting points:
> * Please start new sentences on new lines.
[and other useful feedback about the grammar and substance]

Here goes.

 man8/ld.so.8 |   36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/man8/ld.so.8 b/man8/ld.so.8
index 2fbacae0..72e69f74 100644
--- a/man8/ld.so.8
+++ b/man8/ld.so.8
@@ -64,6 +64,8 @@ in the augmented library path.
 If, however, the binary was linked with the
 .B \-z nodeflib
 linker option, libraries in the default library paths are skipped.
+Libraries installed in hardware capability directories (see below)
+are preferred to other libraries.
 .IP o
 In the default path
 .IR /lib ,
@@ -129,6 +131,40 @@ is set-user-ID or set-group-ID.
 .TP
 .B \-\-audit LIST
 Use objects named in LIST as auditors.
+.SH HARDWARE CAPABILITIES
+Some libraries are compiled using hardware-specific instructions which do
+not exist on every CPU.
+Such libraries should be installed in directories whose names define the
+required hardware capabilities, such as
+.IR /usr/lib/sse2/ .
+The dynamic linker checks these directories against the hardware of the
+machine and selects the most suitable version of a given library.
+Hardware capability directories can be cascaded to combine CPU features.
+The list of supported hardware capability names depends on the CPU.
+The following names are currently recognized:
+.TP
+.B Alpha
+ev4, ev5, ev56, ev6, ev67
+.TP
+.B MIPS
+loongson2e, loongson2f, octeon, octeon2
+.TP
+.B PowerPC
+4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle,
+fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601,
+ppc64, smt, spe, ucache, vsx
+.TP
+.B SPARC
+flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
+.TP
+.B s390
+dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle,
+z900, z990, z9-109, z10, zarch
+.TP
+.TP
+.B x86 (32-bit only)
+acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx,
+mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm
 .SH ENVIRONMENT
 There are four important environment variables.
 .TP
-- 
1.7.10

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] ld.so.8: Document effect of hwcaps on search path

[Michael Kerrisk (man-pages)]

Jonathan,

On Tue, Apr 17, 2012 at 7:27 AM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Wording by Aurelien Jarno from Debian glibc's r4701 (2011-06-04).
>
> Addresses http://bugs.debian.org/622385

No need to write me a new version of the patch, but please send me
some text that *describes* the content of the patch for the changelog.

Cheers,

Michael

> Requested-by: Reuben Thomas <rrt-0NV8xZLkR+A@public.gmane.org>
> Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> ---
> Michael Kerrisk (man-pages) wrote:
>
>> Some minor formatting points:
>> * Please start new sentences on new lines.
> [and other useful feedback about the grammar and substance]
>
> Here goes.
>
>  man8/ld.so.8 |   36 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 36 insertions(+)
>
> diff --git a/man8/ld.so.8 b/man8/ld.so.8
> index 2fbacae0..72e69f74 100644
> --- a/man8/ld.so.8
> +++ b/man8/ld.so.8
> @@ -64,6 +64,8 @@ in the augmented library path.
>  If, however, the binary was linked with the
>  .B \-z nodeflib
>  linker option, libraries in the default library paths are skipped.
> +Libraries installed in hardware capability directories (see below)
> +are preferred to other libraries.
>  .IP o
>  In the default path
>  .IR /lib ,
> @@ -129,6 +131,40 @@ is set-user-ID or set-group-ID.
>  .TP
>  .B \-\-audit LIST
>  Use objects named in LIST as auditors.
> +.SH HARDWARE CAPABILITIES
> +Some libraries are compiled using hardware-specific instructions which do
> +not exist on every CPU.
> +Such libraries should be installed in directories whose names define the
> +required hardware capabilities, such as
> +.IR /usr/lib/sse2/ .
> +The dynamic linker checks these directories against the hardware of the
> +machine and selects the most suitable version of a given library.
> +Hardware capability directories can be cascaded to combine CPU features.
> +The list of supported hardware capability names depends on the CPU.
> +The following names are currently recognized:
> +.TP
> +.B Alpha
> +ev4, ev5, ev56, ev6, ev67
> +.TP
> +.B MIPS
> +loongson2e, loongson2f, octeon, octeon2
> +.TP
> +.B PowerPC
> +4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle,
> +fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601,
> +ppc64, smt, spe, ucache, vsx
> +.TP
> +.B SPARC
> +flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
> +.TP
> +.B s390
> +dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle,
> +z900, z990, z9-109, z10, zarch
> +.TP
> +.TP
> +.B x86 (32-bit only)
> +acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx,
> +mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm
>  .SH ENVIRONMENT
>  There are four important environment variables.
>  .TP
> --
> 1.7.10
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] ld.so.8: Document effect of hwcaps on search path

[Jonathan Nieder]

Michael Kerrisk wrote:
> On Tue, Apr 17, 2012 at 7:27 AM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

>> Wording by Aurelien Jarno from Debian glibc's r4701 (2011-06-04).
>>
>> Addresses http://bugs.debian.org/622385
>
> No need to write me a new version of the patch, but please send me
> some text that *describes* the content of the patch for the changelog.

You mean more than "ld.so.8: Document effect of hwcaps on search
path"?  What sort of information is needed here --- usually I am used
to stating the purpose and overall strategy in the changelog and
letting the patch itself describe the exact change, but I am happy to
adapt if this project has some different convention.

Thanks and sorry for the fuss,
Jonathan
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] ld.so.8: Document effect of hwcaps on search path

[Michael Kerrisk (man-pages)]

On Tue, Apr 17, 2012 at 8:13 AM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Michael Kerrisk wrote:
>> On Tue, Apr 17, 2012 at 7:27 AM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>
>>> Wording by Aurelien Jarno from Debian glibc's r4701 (2011-06-04).
>>>
>>> Addresses http://bugs.debian.org/622385
>>
>> No need to write me a new version of the patch, but please send me
>> some text that *describes* the content of the patch for the changelog.
>
> You mean more than "ld.so.8: Document effect of hwcaps on search
> path"?  What sort of information is needed here --- usually I am used
> to stating the purpose and overall strategy in the changelog and
> letting the patch itself describe the exact change, but I am happy to
> adapt if this project has some different convention.
>
> Thanks and sorry for the fuss,

Actually, sorry -- you're probably right that that description suffices.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] ld.so.8: Document effect of hwcaps on search path

[Michael Kerrisk (man-pages)]

On Tue, Apr 17, 2012 at 7:27 AM, Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Wording by Aurelien Jarno from Debian glibc's r4701 (2011-06-04).
>
> Addresses http://bugs.debian.org/622385
>
> Requested-by: Reuben Thomas <rrt-0NV8xZLkR+A@public.gmane.org>
> Signed-off-by: Jonathan Nieder <jrnieder-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>

Thanks Jonathan. Applied for 3.39.

Cheers,

Michael


> ---
> Michael Kerrisk (man-pages) wrote:
>
>> Some minor formatting points:
>> * Please start new sentences on new lines.
> [and other useful feedback about the grammar and substance]
>
> Here goes.
>
>  man8/ld.so.8 |   36 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 36 insertions(+)
>
> diff --git a/man8/ld.so.8 b/man8/ld.so.8
> index 2fbacae0..72e69f74 100644
> --- a/man8/ld.so.8
> +++ b/man8/ld.so.8
> @@ -64,6 +64,8 @@ in the augmented library path.
>  If, however, the binary was linked with the
>  .B \-z nodeflib
>  linker option, libraries in the default library paths are skipped.
> +Libraries installed in hardware capability directories (see below)
> +are preferred to other libraries.
>  .IP o
>  In the default path
>  .IR /lib ,
> @@ -129,6 +131,40 @@ is set-user-ID or set-group-ID.
>  .TP
>  .B \-\-audit LIST
>  Use objects named in LIST as auditors.
> +.SH HARDWARE CAPABILITIES
> +Some libraries are compiled using hardware-specific instructions which do
> +not exist on every CPU.
> +Such libraries should be installed in directories whose names define the
> +required hardware capabilities, such as
> +.IR /usr/lib/sse2/ .
> +The dynamic linker checks these directories against the hardware of the
> +machine and selects the most suitable version of a given library.
> +Hardware capability directories can be cascaded to combine CPU features.
> +The list of supported hardware capability names depends on the CPU.
> +The following names are currently recognized:
> +.TP
> +.B Alpha
> +ev4, ev5, ev56, ev6, ev67
> +.TP
> +.B MIPS
> +loongson2e, loongson2f, octeon, octeon2
> +.TP
> +.B PowerPC
> +4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle,
> +fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601,
> +ppc64, smt, spe, ucache, vsx
> +.TP
> +.B SPARC
> +flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2
> +.TP
> +.B s390
> +dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle,
> +z900, z990, z9-109, z10, zarch
> +.TP
> +.TP
> +.B x86 (32-bit only)
> +acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx,
> +mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm
>  .SH ENVIRONMENT
>  There are four important environment variables.
>  .TP
> --
> 1.7.10
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] ld.so.8: Document effect of hwcaps on search path

[Mike Frysinger]

[-- Attachment #1: Type: Text/Plain, Size: 158 bytes --]

On Monday 16 April 2012 15:27:03 Jonathan Nieder wrote:
> Here goes.
> 
>  man8/ld.so.8 |   36 ++++++++++++++++++++++++++++++++++++

looks nice!
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]