Patch from AEB: improved DESCRIPTION; clarified distinction between

EACCES and ENOEXEC.

man2/uselib.2

@@ -10,7 +10,7 @@
 .\" manual under the conditions for verbatim copying, provided that the
 .\" entire resulting derived work is distributed under the terms of a
 .\" permission notice identical to this one.
-.\" 
+.\"
 .\" Since the Linux kernel and libraries are constantly changing, this
 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
 .\" responsibility for errors or omissions, or for damages resulting from
@@ -18,25 +18,29 @@
 .\" have taken the same level of care in the production of this manual,
 .\" which is licensed free of charge, as they might when working
 .\" professionally.
-.\" 
+.\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
 .\" Modified by Michael Haardt <michael@moria.de>
 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
-.\" Modified 2004-06-23 by Michael Kerrisk <mtk-manpages@gmx.net>
+.\" Modified 2004-06-23 by Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
+.\" Modified 2005-01-09 by aeb
 .\"
-.TH USELIB 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual"
+.TH USELIB 2 2005-01-09 "Linux 2.6.10" "Linux Programmer's Manual"
 .SH NAME
-uselib \- select shared library
+uselib \- load shared library
 .SH SYNOPSIS
 .B #include <unistd.h>
 .sp
 .BI "int uselib(const char *" library );
 .SH DESCRIPTION
-\fBuselib\fP selects the shared library binary that will be used by
-the calling process.
+The system call \fBuselib\fP serves to load
+a shared library to be used by the calling process.
+It is given a pathname. The address where to load is found
+in the library itself. The library can have any recognized
+binary format.
 .SH "RETURN VALUE"
 On success, zero is returned.  On error, \-1 is returned, and
 .I errno
@@ -52,8 +56,9 @@ the following may also be returned:
 .B EACCES
 The library specified by
 .I library
-is not readable, or the caller does not have search permission
-for one of the directories in the path prefix. (See also
+does not have read or execute permission, or the caller does not have
+search permission for one of the directories in the path prefix.
+(See also
 .BR path_resolution (2).)
 .TP
 .B ENFILE
@@ -62,10 +67,30 @@ The system limit on the total number of open files has been reached.
 .B ENOEXEC
 The file specified by
 .I library
-is not executable, or does not have the correct magic numbers.
+is not an executable of known type,
+e.g., does not have the correct magic numbers.
 .SH "CONFORMING TO"
 \fBuselib()\fP is Linux specific, and should not be used in programs
 intended to be portable.
+.SH NOTES
+\fBuselib()\fP was used by early libc startup code to load
+the shared libraries with names found in an array of names
+in the binary.
+.LP
+.\" libc 4.3.1f - changelog 1993-03-02
+Since libc 4.3.2, startup code tries to prefix these names
+with "/usr/lib", "/lib" and "" before giving up.
+.\" libc 4.3.4 - changelog 1993-04-21
+In libc 4.3.4 and later these names are looked for in the directories
+found in LD_LIBRARY_PATH, and if not found there,
+prefixes "/usr/lib", "/lib" and "/" are tried.
+.LP
+From libc 4.4.4 on only the library "/lib/ld.so" is loaded,
+so that this dynamic library can load the remaining libraries needed
+(again using this call).
+This is also the state of affairs in libc5.
+.LP
+glibc2 does not use this call.
 .SH "SEE ALSO"
 .BR ar (1),
 .BR gcc (1),
@@ -73,5 +98,6 @@ intended to be portable.
 .BR ldd (1),
 .BR mmap (2),
 .BR open (2),
+.BR dlopen (3),
 .BR capability (7),
 .BR ld.so (8)