1 files changed, 61 insertions, 7 deletions

diff --git a/lib/libc/gen/dlopen.3 b/lib/libc/gen/dlopen.3
index 66fa095654da..83850680b401 100644
--- a/lib/libc/gen/dlopen.3
+++ b/lib/libc/gen/dlopen.3
@@ -91,7 +91,8 @@ executable of the process.
 .Fa mode
 controls the way in which external function references from the
 loaded object are bound to their referents.
-It must contain one of the following values:
+It must contain one of the following values, possibly ORed with
+additional flags which will be described subsequently:
 .Bl -tag -width RTLD_LAZYX
 .It Dv RTLD_LAZY
 Each external function reference is resolved when the function is first
@@ -108,6 +109,22 @@ However,
 is useful to ensure that any undefined symbols are discovered during the
 call to
 .Fn dlopen .
+.Pp
+One of the following flags may be ORed into the
+.Fa mode
+argument:
+.Bl -tag -width RTLD_GLOBALX
+.It Dv RTLD_GLOBAL
+Symbols from this shared object and its directed acyclic graph (DAG)
+of needed objects will be available for resolving undefined references
+from all other shared objects.
+.It Dv RTLD_LOCAL
+Symbols in this shared object and its DAG of needed objects will be
+available for resolving undefined references only from other objects
+in the same DAG.  This is the default, but it may be specified
+explicitly with this flag.
+.El
+.Pp
 If 
 .Fn dlopen
 fails, it returns a null pointer, and sets an error condition which may
@@ -127,15 +144,47 @@ can be accessed only through calls to
 Such symbols do not supersede any definition of those symbols already present
 in the address space when the object is loaded, nor are they available to
 satisfy normal dynamic linking references.
-A null pointer supplied as the value of 
-.Fa handle
-is interpreted as a reference to the executable from which the call to 
+.Pp
+If
 .Fn dlsym
+is called with the special
+.Fa handle
+.Dv NULL ,
+it is interpreted as a reference to the executable or shared object
+from which the call
 is being made.  Thus a shared object can reference its own symbols.
+.Pp
+If
 .Fn dlsym
-returns a null pointer if the symbol cannot be found, and sets an error
-condition which may be queried with
-.Fn dlerror .
+is called with the special
+.Fa handle
+.Dv RTLD_DEFAULT ,
+the search for the symbol follows the algorithm used for resolving
+undefined symbols when objects are loaded.  The objects searched are
+as follows, in the given order:
+.Bl -enum
+.It
+The referencing object itself (or the object from which the call to
+.Fn dlsym
+is made), if that object was linked using the
+.Fl Wsymbolic
+option to
+.Xr ld 1 .
+.It
+All objects loaded at program start-up.
+.It
+All objects loaded via
+.Fn dlopen
+which are in needed-object DAGs that also contain the referencing object.
+.It
+All objects loaded via
+.Fn dlopen
+with the
+.Dv RTLD_GLOBAL
+flag set in the
+.Fa mode
+argument.
+.El
 .Pp
 If
 .Fn dlsym
@@ -159,6 +208,11 @@ could access the
 with
 .Li dlsym(RTLD_NEXT, \&"getpid\&") .
 .Pp
+.Fn dlsym
+returns a null pointer if the symbol cannot be found, and sets an error
+condition which may be queried with
+.Fn dlerror .
+.Pp
 .Fn dlerror
 returns a null-terminated character string describing the last error that
 occurred during a call to