1.\" $NetBSD: dlfcn.3,v 1.3 1996/01/09 19:43:34 pk Exp $ 2.\" 3.\" Copyright (c) 1995 Paul Kranenburg 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by Paul Kranenburg. 17.\" 3. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 25.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd September 30, 1995 32.Dt DLFCN 3 33.Os 34.Sh NAME 35.Nm dlopen 36.Nm dlclose 37.Nm dlsym 38.Nm dlctl 39.Nm dlerror 40.Nd dynamic link interface 41.Sh SYNOPSIS 42.Fd #include <dlfcn.h> 43.Ft "void *" 44.Fn dlopen "char *path" "int mode" 45.Ft "int" 46.Fn dlclose "void *handle" 47.Ft "void *" 48.Fn dlsym "void *handle" "char *symbol" 49.Ft "int" 50.Fn dlctl "void *handle" "int cmd" "void *data" 51.Ft "char *" 52.Fn dlerror "void" 53.Sh DESCRIPTION 54These functions provide an interface to the run-time linker 55.Xr ld.so . 56They allow new shared objects to be loaded into the process' address space 57under program control. 58The 59.Fn dlopen 60function takes a name of a shared object as the first argument. The 61shared object is mapped into the address space, relocated and its external 62references are resolved in the same way as is done with the implicitly loaded 63shared libraries at program startup. The argument can either be an absolute 64pathname or it can be of the form 65.Sm off 66.Do Xo lib Ao name Ac .so 67.Op .xx Op .yy Xc 68.Dc 69.Sm on 70in which case the same library search rules apply that are used for 71.Dq intrinsic 72shared library searches. 73The second argument has currently no effect, but should be set to 74.Dv DL_LAZY 75for future compatibility. 76.Fn dlopen 77returns a handle to be used in calls to 78.Fn dlclose , 79.Fn dlsym 80and 81.Fn dlctl . 82If the named shared object has already 83been loaded by a previous call to 84.Fn dlopen 85.Pq and not yet unloaded by Fn dlclose , 86a handle refering to the resident copy is returned. 87.Pp 88.Fn dlclose 89unlinks and removes the object referred to by 90.Fa handle 91from the process address space. If multiple calls to 92.fn dlopen 93have been done on this object 94.Po or the object was one loaded at startup time 95.Pc 96the object is removed when its reference count drops to zero. 97.Pp 98.Fn dlsym 99looks for a definition of 100.Fa symbol 101in the shared object designated by 102.Fa handle . 103The symbols address is returned. If the symbol cannot be resolved, 104.Dv NULL 105is returned. 106.Pp 107.Fn dlctl 108provides an interface similar to 109.Xr ioctl 2 110to control several aspects of the run-time linker's operation. This interface 111is 112.Ud . 113.Pp 114.Fn dlerror 115return a character string representing the most recent error that has 116occurred while processing one of the other functions described here. 117.Sh SEE ALSO 118.Xr ld 1 , 119.Xr rtld 1 , 120.Xr link 5 121.Sh HISTORY 122Some of the 123.Nm dl* 124functions first appeared in SunOS 4. 125.Sh BUGS 126An error that occurs while processing a 127.Fn dlopen 128request results in the termination of the program. 129