Sync with current behavior:

- clarify how paths and parital shared library versions are treated
  with dlopen()
- dlopen() mode parameter is supported now - describe how to use it.
- describe how visiblity effects dlsym() with special handles
- remove bugs section
- formatting improvements
With input from drahn@ and jmc@. okay drahn@, that's fine jmc@

1 files changed, 108 insertions, 61 deletions

diff --git a/share/man/man3/dlfcn.3 b/share/man/man3/dlfcn.3
index 9cf4b12dd58..d448634e65c 100644
--- a/share/man/man3/dlfcn.3
+++ b/share/man/man3/dlfcn.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: dlfcn.3,v 1.17 2004/08/12 23:59:37 jmc Exp $
+.\"	$OpenBSD: dlfcn.3,v 1.18 2006/07/26 12:45:55 kurt Exp $
 .\"	$NetBSD: dlfcn.3,v 1.3 1996/01/09 19:43:34 pk Exp $
 .\"
 .\" Copyright (c) 1995 Paul Kranenburg
@@ -62,38 +62,83 @@ under program control.
 .Pp
 The
 .Fn dlopen
-function takes a name of a shared object as its first argument.
+function takes the name of a shared object as its first argument.
 The shared object is mapped into the address space, relocated, and its external
 references are resolved in the same way as is done with the implicitly loaded
 shared libraries at program startup.
 .Pp
 The
 .Fa path
-argument can either be an absolute pathname or it can be of the form
-.Sm off
-.Do Xo lib Ao name Ac .so
-.Op .xx Op .yy Xc
-.Dc
-.Sm on
-in which case the same library search rules apply that are used for
+parameter can be specified as either an absolute pathname to a shared library
+or just the name of the shared library itself.
+When an absolute pathname is specified,
+only the path provided will be searched for the shared library.
+When just a shared library is specified,
+the same paths will be searched that are used for
 .Dq intrinsic
 shared library searches.
-A null pointer supplied for path is interpreted as a reference to the main
-executable of the process.
-The second argument currently has no effect, but should be set to
-.Dv DL_LAZY
-for future compatibility.
+.Pp
+Shared libraries take the following form:
+.Pp
+.Dl lib\*(Ltname\*(Gt.so[.xx[.yy]]
+.Pp
+When a shared library is specified without a version or with a partial version,
+the same library search rules apply that are used for
+.Dq intrinsic
+shared library searches.
+A null pointer supplied for
+.Fa path
+will return a special
+.Fa handle
+that behaves the same as the
+.Dv RTLD_DEFAULT
+special
+.Fa handle .
+.Pp
+The
+.Fa mode
+parameter specifies symbol resolution time and symbol visibility.
+One of the following values may be used to specify symbol resolution time:
+.Bl -tag -width "RTLD_LAZYXX" -offset indent
+.It Sy RTLD_NOW
+Symbols are resolved immediately.
+.It Sy RTLD_LAZY
+Symbols are resolved when they are first referred to.
+This is the default value if resolution time is unspecified.
+.El
+.Pp
+One of the following values may be used to specify symbol visibility:
+.Pp
+.Bl -tag -width "RTLD_GLOBAL" -compact -offset indent
+.It Sy RTLD_GLOBAL
+The object's symbols and the symbols of its dependencies will be visible to
+other objects.
+.It Sy RTLD_LOCAL
+The object's symbols and the symbols of its dependencies will not be visible to
+other objects.
+This is the default value if visiblity is unspecified.
+.El
+.Pp
+To specify both resolution time and visibility, bitwise inclusive OR one of
+each of the above values together.
+If an object was opened with RTLD_LOCAL and later opened with RTLD_GLOBAL,
+then it is promoted to RTLD_GLOBAL.
 .Pp
 .Fn dlopen
-returns a handle to be used in calls to
+returns a
+.Fa handle
+to be used in calls to
 .Fn dlclose ,
 .Fn dlsym ,
 and
 .Fn dlctl .
 If the named shared object has already been loaded by a previous call to
 .Fn dlopen
-.Pq and not yet unloaded by Fn dlclose ,
-a handle referring to the resident copy is returned.
+and not yet unloaded by
+.Fn dlclose ,
+a
+.Fa handle
+referring to the resident copy is returned.
 .Pp
 .Fn dlclose
 unlinks and removes the object referred to by
@@ -101,59 +146,65 @@ unlinks and removes the object referred to by
 from the process address space.
 If multiple calls to
 .Fn dlopen
-have been done on this object
-.Po or the object was once loaded at startup time
-.Pc
-the object is removed when its reference count drops to zero.
+have been done on this object or the object is a dependency of another object
+then the object is removed when its reference count drops to zero.
 .Pp
 .Fn dlsym
-looks for a definition of
+searches for a definition of
 .Fa symbol
-in the shared object designated by
-.Fa handle .
+in the object designated by
+.Fa handle
+and all shared objects that it depends on.
 The symbol's address is returned.
 If the symbol cannot be resolved,
 .Dv NULL
 is returned.
 .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
+may also be called with special
+.Fa handles .
+In all cases
 .Fn dlsym
-is called with the special
-.Fa handle
-.Dv RTLD_DEFAULT ,
-all the shared objects will be searched in the order they were loaded.
-.Pp
-If
-.Fn dlsym
-is called with the special
-.Fa handle
-.Dv RTLD_NEXT ,
-then the search for the symbol is limited to the shared objects
-which were loaded after the one issuing the call to
+respects symbol visibility as specified by the
+.Fn dlopen
+.Fa mode
+parameter.
+The main executable and all shared objects loaded at program startup are
+globally visible.
+In addition, all shared objects that are a dependency of another object are
+always visible to the object that depends on them.
+The following special
+.Fa handles
+may be used with
+.Fn dlsym :
+.Bl -tag -width "RTLD_DEFAULTXX" -offset indent
+.It Sy NULL
+Interpreted as a reference to the executable or shared object
+from which the call is being made.
+Thus an object can reference its own symbols and the symbols of its
+dependencies without calling
+.Fn dlopen .
+.It Sy RTLD_DEFAULT
+All the visible shared objects and the executable will be searched in the order they
+were loaded.
+.It Sy RTLD_NEXT
+The search for
+.Fa symbol
+is limited to the visible shared objects which were loaded after the one issuing the
+call to
 .Fn dlsym .
-Thus, if the function is called from the main program, all
-the shared libraries are searched.
-If it is called from a shared library, all subsequent shared
-libraries are searched.
-.Pp
-If
+Thus, if
 .Fn dlsym
-is called with the special
-.Fa handle
-.Dv RTLD_SELF ,
-then the search for the symbol is limited to the shared object
-issuing the call to
+is called from the main program, all the visible shared libraries are searched.
+If it is called from a shared library, all subsequently visible shared
+libraries are searched.
+.It Sy RTLD_SELF
+The search for
+.Fa symbol
+is limited to the shared object issuing the call to
 .Fn dlsym
-and those shared objects which were loaded after it.
+and those shared objects which were loaded after it that are visible.
+.El
 .Pp
 .Fn dladdr
 queries the dynamic linker for information about the shared object
@@ -234,7 +285,3 @@ being returned.
 Some of the
 .Nm dl*
 functions first appeared in SunOS 4.
-.Sh BUGS
-An error that occurs while processing a
-.Fn dlopen
-request results in the termination of the program.