dlopen.3: Improvements after input from Carlos O'Donell

Reported-by: Carlos O'Donell <carlos@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man3/dlopen.3 b/man3/dlopen.3
index dc1f00afa8a75459a969c8297a4e4638d0559da8..b023d07b467402941365b99df36dd27daffb0b74 100644 (file)
--- a/man3/dlopen.3
+++ b/man3/dlopen.3
@@ -1,7 +1,7 @@
 .\" Copyright 1995 Yggdrasil Computing, Incorporated.
 .\" written by Adam J. Richter (adam@yggdrasil.com),
 .\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com).
-.\" and Copyright 2003 Michael Kerrisk (mtk.manpages@gmail.com).
+.\" and Copyright 2003, 2015 Michael Kerrisk (mtk.manpages@gmail.com).
 .\"
 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
 .\" This is free documentation; you can redistribute it and/or
@@ -232,12 +232,13 @@ The
 routine, if present, is called only once.
 But a subsequent call with
 .B RTLD_NOW
-may force symbol resolution for a library earlier loaded with
+may force symbol resolution for a shared object earlier loaded with
 .BR RTLD_LAZY .
 .PP
 If
 .BR dlopen ()
 fails for any reason, it returns NULL.
+.\"
 .SS dlmopen()
 This function performs the same task as
 .BR dlopen ()\(emthe
@@ -247,17 +248,22 @@ and
 arguments, as well as the return value, are the same.
 It differs in that it accepts an additional argument,
 .IR lmid ,
-that specifies the link map in which the shared library should be loaded.
+that specifies the link-map list (also referred to as a
+.IR namespace )
+in which the shared object should be loaded.
 (By comparison,
 .BR dlopen ()
-adds the dynamically loaded library to the same link map as
+adds the dynamically loaded shared object to the same namespace as
 the shared object from which the
 .BR dlopen ()
 call is made.)
+The
+.I Lmid_t
+type is an opaque handle that refers to a namespace.
 
 The
 .I lmid
-argument is either the ID of an existing link map
+argument is either the ID of an existing namespace
 .\" FIXME: Is using dlinfo() RTLD_DI_LMID the right technique?
 (which can be obtained using the
 .BR dlinfo (3)
@@ -265,14 +271,20 @@ argument is either the ID of an existing link map
 request) or one of the following special values:
 .TP
 .B LM_ID_BASE
-Load the shared library in the initial link map
-(i.e., the application's link map).
+Load the shared object in the initial namespace
+(i.e., the application's namespace).
 .TP
 .B LM_ID_NEWLM
-Create a new link map and load the shared library in that map.
+Create a new namespace and load the shared object in that namespace.
+The object must have been correctly
+(statically) linked
+to reference all of the other shared objects that it requires,
+since the new namespace is initially empty.
+
 The glibc implementation supports a maximum of
 .\" DL_NNS
-16 link maps.
+16 namespaces.
+.\"
 .SS dlsym()
 The function
 .BR dlsym ()
@@ -437,6 +449,51 @@ Since glibc 2.2.3,
 .BR atexit (3)
 can be used to register an exit handler that is automatically
 called when a library is unloaded.
+.\"
+.SS dlmopen() and namespaces
+A link-map list defines an isolated namespace for the
+resolution of symbols by the dynamic linker.
+Within a namespace,
+dependent shared objects are implicitly loaded according to the usual rules,
+and symbol references are likewise resolved according to the usual rules,
+but such resolution is confined to the definitions provided by the
+objects that have been (explicitly and implicitly) loaded into the namespace.
+
+The
+.BR dlmopen ()
+function permits object-load isolation\(emthe ability
+to load a shared object in a new namespace without
+exposing the rest of the application to the symbols
+made available by the new object.
+Note that the use of the
+.B RTLD_LOCAL
+flag is not sufficient for this purpose,
+since it prevents a shared object's symbols from being available to
+.I any
+other shared object.
+In some cases,
+we may want to make the symbols provided by a dynamically
+loaded library available to (a subset of) other shared objects
+without exposing those symbols to the entire application.
+This can be achieved by using a separate namespace and the
+.B RTLD_GLOBAL
+flag.
+
+Possible uses of
+.BR dlmopen ()
+are plugins where the author of the plugin-loading framework
+can't trust the plugin authors and does not wish
+any undefined symbols from the plugin framework to be resolved to plugin
+symbols.
+Another use is to load the same object more than once.
+Without the use of
+.BR dlopen (),
+this would require the creation of distinct copies of the shared object file.
+Using
+.BR dlopen (),
+this can be achieved by loading the same shared object file into
+different namespaces.
+.\"
 .SS History
 The dlopen interface standard comes from SunOS.
 That system does not have