Document $ORIGIN and rpath

man8/ld.so.8

@@ -70,6 +70,41 @@ and then
 If the binary was linked with
 .B \-z nodeflib
 linker option, this step is skipped.
+.SS $ORIGIN and rpath
+.PP
+.B ld.so
+understands the string
+.I $ORIGIN
+(or equivalently 
+.IR ${ORIGIN} )
+in an rpath specification (DT_RPATH or DT_RUNPATH) to mean
+the directory from which the application was launched.
+Thus, an application located in
+.I somedir/app
+could be compiled with
+.I gcc -Wl,-rpath,'$ORIGIN/../lib'
+so that it finds an associated shared library in
+.I somedir/lib
+no matter where 
+.I somedir 
+is located in the directory hierarchy.
+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
+.\"
+.\" ld.so lets names be abbreviated, so $O will work for $ORIGIN;
+.\" Don't do this!!
 .SH OPTIONS
 .TP
 .B \-\-list