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

Jonathan Nieder
2011-10-20T07:15:38Z

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