share/man/man3/dlfcn.3

   1 .\"     $NetBSD: dlfcn.3,v 1.22 2009/03/10 23:32:26 joerg Exp $
   2 .\"
   3 .\" Copyright (c) 1998 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Paul Kranenburg.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd March 31, 2008
  31 .Dt DLFCN 3
  32 .Os
  33 .Sh NAME
  34 .Nm dlopen ,
  35 .Nm dlclose ,
  36 .Nm dlsym ,
  37 .Nm dladdr ,
  38 .Nm dlctl ,
  39 .Nm dlerror
  40 .Nd dynamic link interface
  41 .Sh LIBRARY
  42 (These functions are not in a library.  They are included in every
  43 dynamically linked program automatically.)
  44 .Sh SYNOPSIS
  45 .In dlfcn.h
  46 .Ft "void *"
  47 .Fn dlopen "const char *path" "int mode"
  48 .Ft "int"
  49 .Fn dlclose "void *handle"
  50 .Ft "void *"
  51 .Fn dlsym "void * restrict handle" "const char * restrict symbol"
  52 .Ft "int"
  53 .Fn dladdr "void * restrict addr" "Dl_info * restrict dli"
  54 .Ft "int"
  55 .Fn dlctl "void *handle" "int cmd" "void *data"
  56 .Ft "char *"
  57 .Fn dlerror "void"
  58 .Sh DESCRIPTION
  59 These functions provide an interface to the run-time linker
  60 .Xr ld.so 1 .
  61 They allow new shared objects to be loaded into the process' address space
  62 under program control.
  63 The
  64 .Fn dlopen
  65 function takes a name of a shared object as the first argument.
  66 The shared object is mapped into the address space, relocated and
  67 its external references are resolved in the same way as is done
  68 with the implicitly loaded shared libraries at program startup.
  69 The argument can either be an absolute pathname or it can be of the form
  70 .Sm off
  71 .Do lib Ao name Ac .so Oo .xx Oo .yy Oc Oc
  72 .Dc
  73 .Sm on
  74 in which case the same library search rules apply that are used for
  75 .Dq intrinsic
  76 shared library searches.
  77 If the first argument is
  78 .Dv NULL ,
  79 .Fn dlopen
  80 returns a handle on the global symbol object. This object
  81 provides access to all symbols from an ordered set of objects consisting
  82 of the original program image and any dependencies loaded during startup.
  83 .Pp
  84 The second argument has currently no effect, but should be set to
  85 .Dv RTLD_LAZY
  86 for future compatibility.
  87 .Fn dlopen
  88 returns a handle to be used in calls to
  89 .Fn dlclose ,
  90 .Fn dlsym
  91 and
  92 .Fn dlctl .
  93 If the named shared object has already
  94 been loaded by a previous call to
  95 .Fn dlopen
  96 .Pq and not yet unloaded by Fn dlclose ,
  97 a handle referring to the resident copy is returned.
  98 .Pp
  99 .Fn dlclose
 100 unlinks and removes the object referred to by
 101 .Fa handle
 102 from the process address space.
 103 If multiple calls to
 104 .Fn dlopen
 105 have been done on this object
 106 .Po or the object was one loaded at startup time
 107 .Pc
 108 the object is removed when its reference count drops to zero.
 109 .Pp
 110 .Fn dlsym
 111 looks for a definition of
 112 .Fa symbol
 113 in the shared object designated by
 114 .Fa handle .
 115 The symbols address is returned.
 116 If the symbol cannot be resolved,
 117 .Dv NULL
 118 is returned.
 119 .Pp
 120 .Fn dladdr
 121 examines all currently mapped shared objects for a symbol whose address --
 122 as mapped in the process address space -- is closest to but not exceeding
 123 the value passed in the first argument
 124 .Fa addr .
 125 The symbols of a shared object are only eligible if
 126 .Va addr
 127 is between the base address of the shared object and the value of the
 128 symbol
 129 .Dq _end
 130 in the same shared object. If no object for which this condition holds
 131 true can be found,
 132 .Fn dladdr
 133 will return 0. Otherwise, a non-zero value is returned and the
 134 .Fa dli
 135 argument will be used to provide information on the selected symbol
 136 and the shared object it is contained in.
 137 The
 138 .Fa dli
 139 argument points at a caller-provided
 140 .Va Dl_info
 141 structure defined as follows:
 142 .Bd -literal -offset indent
 143 typedef struct {
 144         const char  *dli_fname;     /* File defining the symbol */
 145         void        *dli_fbase;     /* Base address */
 146         const char  *dli_sname;     /* Symbol name */
 147         const void  *dli_saddr;     /* Symbol address */
 148 } Dl_info;
 149 .Ed
 150 .Pp
 151 The member
 152 .Va dli_sname
 153 points at the nul-terminated name of the selected symbol, and
 154 .Va dli_saddr
 155 is the actual address
 156 .Pq as it appears in the process address space
 157 of the symbol.
 158 The member
 159 .Va dli_fname
 160 points at the file name corresponding to the shared object in which the
 161 symbol was found, while
 162 .Va dli_fbase
 163 is the base address at which this shared object is loaded in the process
 164 address space.
 165 .Va dli_fname
 166 and
 167 .Va dli_fbase
 168 may be zero if the symbol was found in the internally generated
 169 .Dq copy
 170 section
 171 .Po
 172 see
 173 .Xr link 5
 174 .Pc
 175 which is not associated with a file.
 176 Note: both strings pointed at by
 177 .Va dli_fname
 178 and
 179 .Va dli_sname
 180 reside in memory private to the run-time linker module and should not
 181 be modified by the caller.
 182 .Pp
 183 .Fn dlctl
 184 provides an interface similar to
 185 .Xr ioctl 2
 186 to control several aspects of the run-time linker's operation.
 187 This interface is
 188 .Ud
 189 .Pp
 190 .Fn dlerror
 191 returns a character string representing the most recent error that has
 192 occurred while processing one of the other functions described here.
 193 If no dynamic linking errors have occurred since the last invocation of
 194 .Fn dlerror ,
 195 .Fn dlerror
 196 returns
 197 .Dv NULL .
 198 Thus, invoking
 199 .Fn dlerror
 200 a second time, immediately following a prior invocation, will result in
 201 .Dv NULL
 202 being returned.
 203 .Sh SEE ALSO
 204 .Xr ld 1 ,
 205 .Xr rtld 1 ,
 206 .Xr link 5
 207 .Sh HISTORY
 208 Some of the
 209 .Nm dl*
 210 functions first appeared in SunOS 4.
 211 .Sh BUGS
 212 An error that occurs while processing a
 213 .Fn dlopen
 214 request results in the termination of the program.