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 May 14, 2020
  36 .Dt DLOPEN 3
  37 .Os
  38 .Sh NAME
  39 .Nm dlopen ,
  40 .Nm fdlopen ,
  41 .Nm dlsym ,
  42 .Nm dlvsym ,
  43 .Nm dlfunc ,
  44 .Nm dlerror ,
  45 .Nm dlclose
  46 .Nd programmatic interface to the dynamic linker
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In dlfcn.h
  51 .Ft void *
  52 .Fn dlopen "const char *path" "int mode"
  53 .Ft void *
  54 .Fn fdlopen "int fd" "int mode"
  55 .Ft void *
  56 .Fn dlsym "void * restrict handle" "const char * restrict symbol"
  57 .Ft void *
  58 .Fn dlvsym "void * restrict handle" "const char * restrict symbol" "const char * restrict version"
  59 .Ft dlfunc_t
  60 .Fn dlfunc "void * restrict handle" "const char * restrict symbol"
  61 .Ft char *
  62 .Fn dlerror "void"
  63 .Ft int
  64 .Fn dlclose "void *handle"
  65 .Sh DESCRIPTION
  66 These functions provide a simple programmatic interface to the services of the
  67 dynamic linker.
  68 Operations are provided to add new shared objects to a
  69 program's address space, to obtain the address bindings of symbols
  70 defined by such
  71 objects, and to remove such objects when their use is no longer required.
  72 .Pp
  73 The
  74 .Fn dlopen
  75 function
  76 provides access to the shared object in
  77 .Fa path ,
  78 returning a descriptor that can be used for later
  79 references to the object in calls to
  80 .Fn dlsym ,
  81 .Fn dlvsym
  82 and
  83 .Fn dlclose .
  84 If
  85 .Fa path
  86 was not in the address space prior to the call to
  87 .Fn dlopen ,
  88 it is placed in the address space.
  89 When an object is first loaded into the address space in this way, its
  90 function
  91 .Fn _init ,
  92 if any, is called by the dynamic linker.
  93 If
  94 .Fa path
  95 has already been placed in the address space in a previous call to
  96 .Fn dlopen ,
  97 it is not added a second time, although a reference count of
  98 .Fn dlopen
  99 operations on
 100 .Fa path
 101 is maintained.
 102 A null pointer supplied for
 103 .Fa path
 104 is interpreted as a reference to the main
 105 executable of the process.
 106 The
 107 .Fa mode
 108 argument
 109 controls the way in which external function references from the
 110 loaded object are bound to their referents.
 111 It must contain one of the following values, possibly ORed with
 112 additional flags which will be described subsequently:
 113 .Bl -tag -width RTLD_LAZYX
 114 .It Dv RTLD_LAZY
 115 Each external function reference is resolved when the function is first
 116 called.
 117 .It Dv RTLD_NOW
 118 All external function references are bound immediately by
 119 .Fn dlopen .
 120 .El
 121 .Pp
 122 .Dv RTLD_LAZY
 123 is normally preferred, for reasons of efficiency.
 124 However,
 125 .Dv RTLD_NOW
 126 is useful to ensure that any undefined symbols are discovered during the
 127 call to
 128 .Fn dlopen .
 129 .Pp
 130 One of the following flags may be ORed into the
 131 .Fa mode
 132 argument:
 133 .Bl -tag -width RTLD_NODELETE
 134 .It Dv RTLD_GLOBAL
 135 Symbols from this shared object and its directed acyclic graph (DAG)
 136 of needed objects will be available for resolving undefined references
 137 from all other shared objects.
 138 .It Dv RTLD_LOCAL
 139 Symbols in this shared object and its DAG of needed objects will be
 140 available for resolving undefined references only from other objects
 141 in the same DAG.
 142 This is the default, but it may be specified
 143 explicitly with this flag.
 144 .It Dv RTLD_TRACE
 145 When set, causes dynamic linker to exit after loading all objects
 146 needed by this shared object and printing a summary which includes
 147 the absolute pathnames of all objects, to standard output.
 148 With this flag
 149 .Fn dlopen
 150 will return to the caller only in the case of error.
 151 .It Dv RTLD_NODELETE
 152 Prevents unload of the loaded object on
 153 .Fn dlclose .
 154 The same behaviour may be requested by
 155 .Fl "z nodelete"
 156 option of the static linker
 157 .Xr ld 1 .
 158 .It Dv RTLD_NOLOAD
 159 Only return valid handle for the object if it is already loaded in
 160 the process address space, otherwise
 161 .Dv NULL
 162 is returned.
 163 Other mode flags may be specified, which will be applied for promotion
 164 for the found object.
 165 .It Dv RTLD_DEEPBIND
 166 Symbols from the loaded library are put before global symbols when
 167 resolving symbolic references originated from the library.
 168 .El
 169 .Pp
 170 If
 171 .Fn dlopen
 172 fails, it returns a null pointer, and sets an error condition which may
 173 be interrogated with
 174 .Fn dlerror .
 175 .Pp
 176 The
 177 .Fn fdlopen
 178 function is similar to
 179 .Fn dlopen ,
 180 but it takes the file descriptor argument
 181 .Fa fd ,
 182 which is used for the file operations needed to load an object
 183 into the address space.
 184 The file descriptor
 185 .Fa fd
 186 is not closed by the function regardless a result of execution,
 187 but a duplicate of the file descriptor is.
 188 This may be important if a
 189 .Xr lockf 3
 190 lock is held on the passed descriptor.
 191 The
 192 .Fa fd
 193 argument -1 is interpreted as a reference to the main
 194 executable of the process, similar to
 195 .Va NULL
 196 value for the
 197 .Fa name
 198 argument to
 199 .Fn dlopen .
 200 The
 201 .Fn fdlopen
 202 function can be used by the code that needs to perform
 203 additional checks on the loaded objects, to prevent races with
 204 symlinking or renames.
 205 .Pp
 206 The
 207 .Fn dlsym
 208 function
 209 returns the address binding of the symbol described in the null-terminated
 210 character string
 211 .Fa symbol ,
 212 as it occurs in the shared object identified by
 213 .Fa handle .
 214 The symbols exported by objects added to the address space by
 215 .Fn dlopen
 216 can be accessed only through calls to
 217 .Fn dlsym .
 218 Such symbols do not supersede any definition of those symbols already present
 219 in the address space when the object is loaded, nor are they available to
 220 satisfy normal dynamic linking references.
 221 .Pp
 222 If
 223 .Fn dlsym
 224 is called with the special
 225 .Fa handle
 226 .Dv NULL ,
 227 it is interpreted as a reference to the executable or shared object
 228 from which the call
 229 is being made.
 230 Thus a shared object can reference its own symbols.
 231 .Pp
 232 If
 233 .Fn dlsym
 234 is called with the special
 235 .Fa handle
 236 .Dv RTLD_DEFAULT ,
 237 the search for the symbol follows the algorithm used for resolving
 238 undefined symbols when objects are loaded.
 239 The objects searched are
 240 as follows, in the given order:
 241 .Bl -enum
 242 .It
 243 The referencing object itself (or the object from which the call to
 244 .Fn dlsym
 245 is made), if that object was linked using the
 246 .Fl Bsymbolic
 247 option to
 248 .Xr ld 1 .
 249 .It
 250 All objects loaded at program start-up.
 251 .It
 252 All objects loaded via
 253 .Fn dlopen
 254 with the
 255 .Dv RTLD_GLOBAL
 256 flag set in the
 257 .Fa mode
 258 argument.
 259 .It
 260 All objects loaded via
 261 .Fn dlopen
 262 which are in needed-object DAGs that also contain the referencing object.
 263 .El
 264 .Pp
 265 If
 266 .Fn dlsym
 267 is called with the special
 268 .Fa handle
 269 .Dv RTLD_NEXT ,
 270 then the search for the symbol is limited to the shared objects
 271 which were loaded after the one issuing the call to
 272 .Fn dlsym .
 273 Thus, if the function is called from the main program, all
 274 the shared libraries are searched.
 275 If it is called from a shared library, all subsequent shared
 276 libraries are searched.
 277 .Dv RTLD_NEXT
 278 is useful for implementing wrappers around library functions.
 279 For example, a wrapper function
 280 .Fn getpid
 281 could access the
 282 .Dq real
 283 .Fn getpid
 284 with
 285 .Li dlsym(RTLD_NEXT, \&"getpid\&") .
 286 (Actually, the
 287 .Fn dlfunc
 288 interface, below, should be used, since
 289 .Fn getpid
 290 is a function and not a data object.)
 291 .Pp
 292 If
 293 .Fn dlsym
 294 is called with the special
 295 .Fa handle
 296 .Dv RTLD_SELF ,
 297 then the search for the symbol is limited to the shared object
 298 issuing the call to
 299 .Fn dlsym
 300 and those shared objects which were loaded after it.
 301 .Pp
 302 The
 303 .Fn dlsym
 304 function
 305 returns a null pointer if the symbol cannot be found, and sets an error
 306 condition which may be queried with
 307 .Fn dlerror .
 308 .Pp
 309 The
 310 .Fn dlvsym
 311 function behaves like
 312 .Fn dlsym ,
 313 but takes an extra argument
 314 .Fa version :
 315 a null-terminated character string which is used to request a specific version
 316 of
 317 .Fa symbol .
 318 .Pp
 319 The
 320 .Fn dlfunc
 321 function
 322 implements all of the behavior of
 323 .Fn dlsym ,
 324 but has a return type which can be cast to a function pointer without
 325 triggering compiler diagnostics.
 326 (The
 327 .Fn dlsym
 328 function
 329 returns a data pointer; in the C standard, conversions between
 330 data and function pointer types are undefined.
 331 Some compilers and
 332 .Xr lint 1
 333 utilities warn about such casts.)
 334 The precise return type of
 335 .Fn dlfunc
 336 is unspecified; applications must cast it to an appropriate function pointer
 337 type.
 338 .Pp
 339 The
 340 .Fn dlerror
 341 function
 342 returns a null-terminated character string describing the last error that
 343 occurred during a call to
 344 .Fn dlopen ,
 345 .Fn dladdr ,
 346 .Fn dlinfo ,
 347 .Fn dlsym ,
 348 .Fn dlvsym ,
 349 .Fn dlfunc ,
 350 or
 351 .Fn dlclose .
 352 If no such error has occurred,
 353 .Fn dlerror
 354 returns a null pointer.
 355 At each call to
 356 .Fn dlerror ,
 357 the error indication is reset.
 358 Thus in the case of two calls
 359 to
 360 .Fn dlerror ,
 361 where the second call follows the first immediately, the second call
 362 will always return a null pointer.
 363 .Pp
 364 The
 365 .Fn dlclose
 366 function
 367 deletes a reference to the shared object referenced by
 368 .Fa handle .
 369 If the reference count drops to 0, the object is removed from the
 370 address space, and
 371 .Fa handle
 372 is rendered invalid.
 373 Just before removing a shared object in this way, the dynamic linker
 374 calls the object's
 375 .Fn _fini
 376 function, if such a function is defined by the object.
 377 If
 378 .Fn dlclose
 379 is successful, it returns a value of 0.
 380 Otherwise it returns -1, and sets an error condition that can be
 381 interrogated with
 382 .Fn dlerror .
 383 .Pp
 384 The object-intrinsic functions
 385 .Fn _init
 386 and
 387 .Fn _fini
 388 are called with no arguments, and are not expected to return values.
 389 .Sh NOTES
 390 ELF executables need to be linked
 391 using the
 392 .Fl export-dynamic
 393 option to
 394 .Xr ld 1
 395 for symbols defined in the executable to become visible to
 396 .Fn dlsym ,
 397 .Fn dlvsym
 398 or
 399 .Fn dlfunc
 400 .Pp
 401 Other ELF platforms require linking with
 402 .Lb libdl
 403 to provide
 404 .Fn dlopen
 405 and other functions.
 406 .Fx
 407 does not require linking with the library, but supports it for compatibility.
 408 .Pp
 409 In previous implementations, it was necessary to prepend an underscore
 410 to all external symbols in order to gain symbol
 411 compatibility with object code compiled from the C language.
 412 This is
 413 still the case when using the (obsolete)
 414 .Fl aout
 415 option to the C language compiler.
 416 .Sh ERRORS
 417 The
 418 .Fn dlopen ,
 419 .Fn fdlopen ,
 420 .Fn dlsym ,
 421 .Fn dlvsym ,
 422 and
 423 .Fn dlfunc
 424 functions
 425 return a null pointer in the event of errors.
 426 The
 427 .Fn dlclose
 428 function
 429 returns 0 on success, or -1 if an error occurred.
 430 Whenever an error has been detected, a message detailing it can be
 431 retrieved via a call to
 432 .Fn dlerror .
 433 .Sh SEE ALSO
 434 .Xr ld 1 ,
 435 .Xr rtld 1 ,
 436 .Xr dladdr 3 ,
 437 .Xr dlinfo 3 ,
 438 .Xr link 5