lib/libc/gen/dlopen.3

   1 .\" This source code is a product of Sun Microsystems, Inc. and is provided
   2 .\" for unrestricted use provided that this legend is included on all tape
   3 .\" media and as a part of the software program in whole or part.  Users
   4 .\" may copy or modify this source code without charge, but are not authorized
   5 .\" to license or distribute it to anyone else except as part of a product or
   6 .\" program developed by the user.
   7 .\"
   8 .\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC.
   9 .\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY
  10 .\" OF SUCH SOURCE CODE FOR ANY PURPOSE.  IT IS PROVIDED "AS IS" WITHOUT
  11 .\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND.  SUN MICROSYSTEMS, INC. DISCLAIMS
  12 .\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED
  13 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN
  14 .\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT,
  15 .\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  16 .\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY.
  17 .\"
  18 .\" This source code is provided with no support and without any obligation on
  19 .\" the part of Sun Microsystems, Inc. to assist in its use, correction,
  20 .\" modification or enhancement.
  21 .\"
  22 .\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
  23 .\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS
  24 .\" SOURCE CODE OR ANY PART THEREOF.
  25 .\"
  26 .\" Sun Microsystems, Inc.
  27 .\" 2550 Garcia Avenue
  28 .\" Mountain View, California 94043
  29 .\"
  30 .\" Copyright (c) 1991 Sun Microsystems, Inc.
  31 .\"
  32 .\" @(#) dlopen.3 1.6 90/01/31 SMI
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd September 24, 1989
  36 .Os FreeBSD
  37 .Dt DLOPEN 3
  38 .Sh NAME
  39 .Nm dlopen, dlsym, dlerror, dlclose
  40 .Nd programmatic interface to the dynamic linker
  41 .Sh SYNOPSIS
  42 .Fd #include <dlfcn.h>
  43 .Ft void *
  44 .Fn dlopen "const char *path" "int mode"
  45 .Ft void *
  46 .Fn dlsym "void *handle" "const char *symbol"
  47 .Ft const char *
  48 .Fn dlerror "void"
  49 .Ft int
  50 .Fn dlclose "void *handle"
  51 .Sh DESCRIPTION
  52 These functions provide a simple programmatic interface to the services of the
  53 dynamic linker.
  54 Operations are provided to add new shared objects to a
  55 program's address space, to obtain the address bindings of symbols
  56 defined by such
  57 objects, and to remove such objects when their use is no longer required.
  58 .Pp
  59 .Fn dlopen
  60 provides access to the shared object in
  61 .Fa path ,
  62 returning a descriptor that can be used for later
  63 references to the object in calls to
  64 .Fn dlsym
  65 and
  66 .Fn dlclose .
  67 If
  68 .Fa path
  69 was not in the address space prior to the call to
  70 .Fn dlopen ,
  71 it is placed in the address space.
  72 When an object is first loaded into the address space in this way, its
  73 function
  74 .Fn _init ,
  75 if any, is called by the dynamic linker.
  76 (Note that
  77 .Ql _init
  78 is the name as expressed in the C language.
  79 From assembly language, the name would appear as
  80 .Ql __init
  81 instead.)
  82 If
  83 .Fa path
  84 has already been placed in the address space in a previous call to
  85 .Fn dlopen ,
  86 it is not added a second time, although a reference count of
  87 .Fn dlopen
  88 operations on
  89 .Fa path
  90 is maintained.
  91 A null pointer supplied for
  92 .Fa path
  93 is interpreted as a reference to the main
  94 executable of the process.
  95 .Fa mode
  96 controls the way in which external function references from the
  97 loaded object are bound to their referents.
  98 It must contain one of the following values:
  99 .Bl -tag -width RTLD_LAZYX
 100 .It Dv RTLD_LAZY
 101 Each external function reference is resolved when the function is first
 102 called.
 103 .It Dv RTLD_NOW
 104 All external function references are bound immediately by
 105 .Fn dlopen .
 106 .El
 107 .Pp
 108 .Dv RTLD_LAZY
 109 is normally preferred, for reasons of efficiency.
 110 However,
 111 .Dv RTLD_NOW
 112 is useful to ensure that any undefined symbols are discovered during the
 113 call to
 114 .Fn dlopen .
 115 If
 116 .Fn dlopen
 117 fails, it returns a null pointer, and sets an error condition which may
 118 be interrogated with
 119 .Fn dlerror .
 120 .Pp
 121 .Fn dlsym
 122 returns the address binding of the symbol described in the null-terminated
 123 character string
 124 .Fa symbol ,
 125 as it occurs in the shared object identified by
 126 .Fa handle .
 127 Note that
 128 .Fa symbol
 129 is the assembly language representation of the symbol name.
 130 The assembly language representation of a C language symbol contains an
 131 extra underscore at the beginning.
 132 For example, the symbol
 133 .Ql foo
 134 in C would appear as
 135 .Ql _foo
 136 in assembly language, and in the
 137 .Fa symbol
 138 argument to
 139 .Fn dlsym .
 140 The symbols exported by objects added to the address space by
 141 .Fn dlopen
 142 can be accessed only through calls to
 143 .Fn dlsym .
 144 Such symbols do not supersede any definition of those symbols already present
 145 in the address space when the object is loaded, nor are they available to
 146 satisfy normal dynamic linking references.
 147 A null pointer supplied as the value of
 148 .Fa handle
 149 is interpreted as a reference to the executable from which the call to
 150 .Fn dlsym
 151 is being made.  Thus a shared object can reference its own symbols.
 152 .Fn dlsym
 153 returns a null pointer if the symbol cannot be found, and sets an error
 154 condition which may be queried with
 155 .Fn dlerror .
 156 .Pp
 157 If
 158 .Fn dlsym
 159 is called with the special
 160 .Fa handle
 161 .Dv RTLD_NEXT ,
 162 then the search for the symbol is limited to the shared objects
 163 which were loaded after the one issuing the call to
 164 .Fn dlsym .
 165 Thus, if the function is called from the main program, all
 166 the shared libraries are searched.
 167 If it is called from a shared library, all subsequent shared
 168 libraries are searched.
 169 .Dv RTLD_NEXT
 170 is useful for implementing wrappers around library functions.
 171 For example, a wrapper function
 172 .Fn getpid
 173 could access the
 174 .Dq real
 175 .Fn getpid
 176 with
 177 .Li dlsym(RTLD_NEXT, \&"_getpid\&") .
 178 .Pp
 179 .Fn dlerror
 180 returns a null-terminated character string describing the last error that
 181 occurred during a call to
 182 .Fn dlopen ,
 183 .Fn dlsym ,
 184 or
 185 .Fn dlclose .
 186 If no such error has occurred,
 187 .Fn dlerror
 188 returns a null pointer.
 189 At each call to
 190 .Fn dlerror ,
 191 the error indication is reset.  Thus in the case of two calls
 192 to
 193 .Fn dlerror ,
 194 where the second call follows the first immediately, the second call
 195 will always return a null pointer.
 196 .Pp
 197 .Fn dlclose
 198 deletes a reference to the shared object referenced by
 199 .Fa handle .
 200 If the reference count drops to 0, the object is removed from the
 201 address space, and
 202 .Fa handle
 203 is rendered invalid.
 204 Just before removing a shared object in this way, the dynamic linker
 205 calls the object's
 206 .Fn _fini
 207 function, if such a function is defined by the object.
 208 As with
 209 .Ql _init ,
 210 .Ql _fini
 211 is the C language name of the function.
 212 If
 213 .Fn dlclose
 214 is successful, it returns a value of 0.
 215 Otherwise it returns -1, and sets an error condition that can be
 216 interrogated with
 217 .Fn dlerror .
 218 .Pp
 219 The object-intrinsic functions
 220 .Fn _init
 221 and
 222 .Fn _fini
 223 are called with no arguments, and are not expected to return values.
 224 .Sh NOTES
 225 ELF executables need to be linked
 226 using the
 227 .Fl export-dynamic
 228 option to
 229 .Xr ld 1
 230 for symbols defined in the executable to become visible to
 231 .Fn dlsym .
 232 .Sh ERRORS
 233 .Fn dlopen
 234 and
 235 .Fn dlsym
 236 return the null pointer in the event of errors.
 237 .Fn dlclose
 238 returns 0 on success, or -1 if an error occurred.
 239 Whenever an error has been detected, a message detailing it can be
 240 retrieved via a call to
 241 .Fn dlerror .
 242 .Sh SEE ALSO
 243 .Xr ld 1 ,
 244 .Xr rtld 1 ,
 245 .Xr link 5
 246