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 January 2, 2019
  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 .El
 166 .Pp
 167 If
 168 .Fn dlopen
 169 fails, it returns a null pointer, and sets an error condition which may
 170 be interrogated with
 171 .Fn dlerror .
 172 .Pp
 173 The
 174 .Fn fdlopen
 175 function is similar to
 176 .Fn dlopen ,
 177 but it takes the file descriptor argument
 178 .Fa fd ,
 179 which is used for the file operations needed to load an object
 180 into the address space.
 181 The file descriptor
 182 .Fa fd
 183 is not closed by the function regardless a result of execution,
 184 but a duplicate of the file descriptor is.
 185 This may be important if a
 186 .Xr lockf 3
 187 lock is held on the passed descriptor.
 188 The
 189 .Fa fd
 190 argument -1 is interpreted as a reference to the main
 191 executable of the process, similar to
 192 .Va NULL
 193 value for the
 194 .Fa name
 195 argument to
 196 .Fn dlopen .
 197 The
 198 .Fn fdlopen
 199 function can be used by the code that needs to perform
 200 additional checks on the loaded objects, to prevent races with
 201 symlinking or renames.
 202 .Pp
 203 The
 204 .Fn dlsym
 205 function
 206 returns the address binding of the symbol described in the null-terminated
 207 character string
 208 .Fa symbol ,
 209 as it occurs in the shared object identified by
 210 .Fa handle .
 211 The symbols exported by objects added to the address space by
 212 .Fn dlopen
 213 can be accessed only through calls to
 214 .Fn dlsym .
 215 Such symbols do not supersede any definition of those symbols already present
 216 in the address space when the object is loaded, nor are they available to
 217 satisfy normal dynamic linking references.
 218 .Pp
 219 If
 220 .Fn dlsym
 221 is called with the special
 222 .Fa handle
 223 .Dv NULL ,
 224 it is interpreted as a reference to the executable or shared object
 225 from which the call
 226 is being made.
 227 Thus a shared object can reference its own symbols.
 228 .Pp
 229 If
 230 .Fn dlsym
 231 is called with the special
 232 .Fa handle
 233 .Dv RTLD_DEFAULT ,
 234 the search for the symbol follows the algorithm used for resolving
 235 undefined symbols when objects are loaded.
 236 The objects searched are
 237 as follows, in the given order:
 238 .Bl -enum
 239 .It
 240 The referencing object itself (or the object from which the call to
 241 .Fn dlsym
 242 is made), if that object was linked using the
 243 .Fl Bsymbolic
 244 option to
 245 .Xr ld 1 .
 246 .It
 247 All objects loaded at program start-up.
 248 .It
 249 All objects loaded via
 250 .Fn dlopen
 251 with the
 252 .Dv RTLD_GLOBAL
 253 flag set in the
 254 .Fa mode
 255 argument.
 256 .It
 257 All objects loaded via
 258 .Fn dlopen
 259 which are in needed-object DAGs that also contain the referencing object.
 260 .El
 261 .Pp
 262 If
 263 .Fn dlsym
 264 is called with the special
 265 .Fa handle
 266 .Dv RTLD_NEXT ,
 267 then the search for the symbol is limited to the shared objects
 268 which were loaded after the one issuing the call to
 269 .Fn dlsym .
 270 Thus, if the function is called from the main program, all
 271 the shared libraries are searched.
 272 If it is called from a shared library, all subsequent shared
 273 libraries are searched.
 274 .Dv RTLD_NEXT
 275 is useful for implementing wrappers around library functions.
 276 For example, a wrapper function
 277 .Fn getpid
 278 could access the
 279 .Dq real
 280 .Fn getpid
 281 with
 282 .Li dlsym(RTLD_NEXT, \&"getpid\&") .
 283 (Actually, the
 284 .Fn dlfunc
 285 interface, below, should be used, since
 286 .Fn getpid
 287 is a function and not a data object.)
 288 .Pp
 289 If
 290 .Fn dlsym
 291 is called with the special
 292 .Fa handle
 293 .Dv RTLD_SELF ,
 294 then the search for the symbol is limited to the shared object
 295 issuing the call to
 296 .Fn dlsym
 297 and those shared objects which were loaded after it.
 298 .Pp
 299 The
 300 .Fn dlsym
 301 function
 302 returns a null pointer if the symbol cannot be found, and sets an error
 303 condition which may be queried with
 304 .Fn dlerror .
 305 .Pp
 306 The
 307 .Fn dlvsym
 308 function behaves like
 309 .Fn dlsym ,
 310 but takes an extra argument
 311 .Fa version :
 312 a null-terminated character string which is used to request a specific version
 313 of
 314 .Fa symbol .
 315 .Pp
 316 The
 317 .Fn dlfunc
 318 function
 319 implements all of the behavior of
 320 .Fn dlsym ,
 321 but has a return type which can be cast to a function pointer without
 322 triggering compiler diagnostics.
 323 (The
 324 .Fn dlsym
 325 function
 326 returns a data pointer; in the C standard, conversions between
 327 data and function pointer types are undefined.
 328 Some compilers and
 329 .Xr lint 1
 330 utilities warn about such casts.)
 331 The precise return type of
 332 .Fn dlfunc
 333 is unspecified; applications must cast it to an appropriate function pointer
 334 type.
 335 .Pp
 336 The
 337 .Fn dlerror
 338 function
 339 returns a null-terminated character string describing the last error that
 340 occurred during a call to
 341 .Fn dlopen ,
 342 .Fn dladdr ,
 343 .Fn dlinfo ,
 344 .Fn dlsym ,
 345 .Fn dlvsym ,
 346 .Fn dlfunc ,
 347 or
 348 .Fn dlclose .
 349 If no such error has occurred,
 350 .Fn dlerror
 351 returns a null pointer.
 352 At each call to
 353 .Fn dlerror ,
 354 the error indication is reset.
 355 Thus in the case of two calls
 356 to
 357 .Fn dlerror ,
 358 where the second call follows the first immediately, the second call
 359 will always return a null pointer.
 360 .Pp
 361 The
 362 .Fn dlclose
 363 function
 364 deletes a reference to the shared object referenced by
 365 .Fa handle .
 366 If the reference count drops to 0, the object is removed from the
 367 address space, and
 368 .Fa handle
 369 is rendered invalid.
 370 Just before removing a shared object in this way, the dynamic linker
 371 calls the object's
 372 .Fn _fini
 373 function, if such a function is defined by the object.
 374 If
 375 .Fn dlclose
 376 is successful, it returns a value of 0.
 377 Otherwise it returns -1, and sets an error condition that can be
 378 interrogated with
 379 .Fn dlerror .
 380 .Pp
 381 The object-intrinsic functions
 382 .Fn _init
 383 and
 384 .Fn _fini
 385 are called with no arguments, and are not expected to return values.
 386 .Sh NOTES
 387 ELF executables need to be linked
 388 using the
 389 .Fl export-dynamic
 390 option to
 391 .Xr ld 1
 392 for symbols defined in the executable to become visible to
 393 .Fn dlsym ,
 394 .Fn dlvsym
 395 or
 396 .Fn dlfunc
 397 .Pp
 398 Other ELF platforms require linking with
 399 .Lb libdl
 400 to provide
 401 .Fn dlopen
 402 and other functions.
 403 .Fx
 404 does not require linking with the library, but supports it for compatibility.
 405 .Pp
 406 In previous implementations, it was necessary to prepend an underscore
 407 to all external symbols in order to gain symbol
 408 compatibility with object code compiled from the C language.
 409 This is
 410 still the case when using the (obsolete)
 411 .Fl aout
 412 option to the C language compiler.
 413 .Sh ERRORS
 414 The
 415 .Fn dlopen ,
 416 .Fn fdlopen ,
 417 .Fn dlsym ,
 418 .Fn dlvsym ,
 419 and
 420 .Fn dlfunc
 421 functions
 422 return a null pointer in the event of errors.
 423 The
 424 .Fn dlclose
 425 function
 426 returns 0 on success, or -1 if an error occurred.
 427 Whenever an error has been detected, a message detailing it can be
 428 retrieved via a call to
 429 .Fn dlerror .
 430 .Sh SEE ALSO
 431 .Xr ld 1 ,
 432 .Xr rtld 1 ,
 433 .Xr dladdr 3 ,
 434 .Xr dlinfo 3 ,
 435 .Xr link 5