Man page for dlfcn.h

share/man/man3/dlfcn.3

@@ -0,0 +1,120 @@
+.\"	$NetBSD: dlfcn.3,v 1.1 1995/09/30 21:25:24 pk Exp $
+.\"
+.\" Copyright (c) 1995 Paul Kranenburg
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"      This product includes software developed by Paul Kranenburg.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd September 30, 1995
+.Dt DLFCN 3
+.Os
+.Sh NAME
+.Nm dlopen
+.Nm dlclose
+.Nm dlsym
+.Nm dlctl
+.Nm dlerror
+.Nd dynamic link interface
+.Sh SYNOPSIS
+.Fd #include <dlfcn.h>
+.Ft "void *"
+.Fn dlopen "char *path" "int mode"
+.Ft "int"
+.Fn dlclose "void *handle"
+.Ft "void *"
+.Fn dlsym "void *handle" "char *symbol"
+.Ft "int"
+.Fn dlctl "void *handle" "int cmd" "void *data"
+.Ft "char *"
+.Fn dlerror "void"
+.Sh DESCRIPTION
+These functions provide an interface to the run-time linker
+.Xr ld.so .
+They allow new shared objects to be loaded into the process' address space
+under program control.
+The
+.Fn dlopen
+function takes a pathname of a shared object as the 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.
+The second argument has currently no effect, but should be set to
+.Dv DL_LAZY
+for future compatibility.
+.Fn dlopen
+returns a 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 refering to the resident copy is returned.
+.Pp
+.Fn dlclose
+unlinks and removes the object referred to by
+.Fa handle
+from the process address space. If multiple calls to
+.fn dlopen
+have been done on this object
+.Po or the object was one loaded at startup time
+.Pc
+the object is removed when its reference count drops to zero.
+.Pp
+.Fn dlsym
+looks for a definition of
+.Fa symbol
+in the shared object designated by
+.Fa handle .
+The symbols address is returned. If the symbol cannot be resolved,
+.Dv NULL
+is returned.
+.Pp
+.Fn dlctl
+provides an interface similar to
+.Xr ioctl 2
+to control several aspects of the run-time linker's operation. This interface
+is
+.Ud .
+.Pp
+.Fn dlerror
+return a character string representing the most recent error that has
+occurred while processing one of the other functions described here.
+.Sh SEE ALSO
+.Xr ld 1 ,
+.Xr rtld 1 ,
+.Xr link 5
+.Sh HISTORY
+The
+.Nm dl*
+functions appeared in
+.Nx 1.0
+.Sh BUGS
+An error that occurs while processing a
+.Fn dlopen
+request results in the termination of the program.