doc/man/man3/dlopen.3

   1 .Dd February 8, 2005
   2 .Os
   3 .Dt DLOPEN 3
   4 .Sh NAME
   5 .Nm dlopen
   6 .Nd load and link a dynamic library or bundle
   7 .Sh SYNOPSIS
   8 .In dlfcn.h
   9 .Ft void*
  10 .Fn dlopen "const char* path" "int mode"
  11 .Sh DESCRIPTION
  12 .Fn dlopen
  13 examines the mach-o file specified by
  14 .Fa path .
  15 If the file is compatible with the current process and has not already been
  16 loaded into the current process, it is loaded and linked.  After being linked,
  17 if it contains any initializer functions, they are called, before
  18 .Fn dlopen
  19 returns.
  20 .Fn dlopen
  21 can load dynamic libraries and bundles.  It returns a handle that can
  22 be used with
  23 .Fn dlsym
  24 and
  25 .Fn dlclose .
  26 A second call to
  27 .Fn dlopen
  28 with the same path will return the same handle, but the internal reference
  29 count for the handle will be incremented.  Therefore all
  30 .Fn dlopen
  31 calls should be balanced with a
  32 .Fn dlclose
  33 call.
  34 .Pp
  35 If a null pointer is passed in
  36 .Fa path ,
  37 .Fn dlopen
  38 returns a handle equivalent to RTLD_DEFAULT.
  39 .Pp
  40 .Fa mode
  41 contains options to
  42 .Fn dlopen .
  43 It must contain one or more of the following values, possibly ORed together:
  44 .Pp
  45 .Bl -tag -width RTLD_LAZYX
  46 .It Dv RTLD_LAZY
  47 Each external function reference is bound the first time the function is called.
  48 .It Dv RTLD_NOW
  49 All external function references are bound immediately during the call to
  50 .Fn dlopen .
  51 .El
  52 .Pp
  53 .Dv RTLD_LAZY
  54 is normally preferred, for reasons of efficiency.
  55 However,
  56 .Dv RTLD_NOW
  57 is useful to ensure that any undefined symbols are discovered during the
  58 call to
  59 .Fn dlopen .
  60 If neither
  61 RTLD_LAZY nor RTLD_NOW is specified, the default is RTLD_LAZY.
  62 .Pp
  63 One of the following flags may be ORed into the
  64 .Fa mode
  65 argument:
  66 .Bl -tag -width RTLD_GLOBALX
  67 .It Dv RTLD_GLOBAL
  68 Symbols exported from this image (dynamic library or bundle) will be available to any
  69 images build with -flat_namespace option to
  70 .Xr ld 1
  71 or to calls to
  72 .Fn dlsym
  73 when using a special handle.
  74 .It Dv RTLD_LOCAL
  75 Symbols exported from this image (dynamic library or bundle) are generally hidden
  76 and only availble to
  77 .Fn dlsym
  78 when directly using the handle returned by this call to
  79 .Fn dlopen .
  80 If neither
  81 RTLD_GLOBAL nor RTLD_LOCAL is specified, the default is RTLD_GLOBAL.
  82 .El
  83 .Sh SEARCHING
  84 .Fn dlopen
  85 uses a series of steps to find a compatible mach-o file.  The first compatible file found is used.
  86 .Pp
  87 1) If the directory specified by
  88 .Fa path
  89 does not contain a slash '/' (i.e. it is a leaf name) then the environment variable LD_LIBRARY_PATH is
  90 used.  LD_LIBRARY_PATH should be a colon seperated list of directories.
  91 .Fn dlopen
  92 searches each directory, in the order specified, for the leaf name
  93 .Fa path .
  94 .Pp
  95 2) If DYLD_LIBRARY_PATH is set, then those directories are searched, in order,
  96 with the leaf name of
  97 .Fa path .
  98 .Pp
  99 3) If DYLD_FALLBACK_LIBRARY_PATH is set, then those directories are searched, in order
 100 with the leaf name of
 101 .Fa path .
 102 If DYLD_FALLBACK_LIBRARY_PATH is not set, then the following directories are searched: $HOME/lib, /usr/local/lib, /usr/lib
 103 .Pp
 104 4) Lastly,
 105 .Fa path
 106 is tried as-is as a regular file path.  That means it might resolve relative to the current working directory.
 107 .Pp
 108 Note: There are no configuration files to control dlopen searching.
 109 .Pp
 110 Note: Mac OS X uses "fat" files to combine 32-bit and 64-bit libraries.  This means there are no separate 32-bit and 64-bit search paths.
 111 .Pp
 112 .Sh RETURN VALUES
 113 If
 114 .Fn dlopen
 115 fails, it returns a null pointer, and sets an error condition which may be interrogated with
 116 .Fn dlerror .
 117 .Sh AUTHORS
 118 Mac OS X 10.3 incorporated the dlcompat package written by Jorge Acereda <jacereda@users.sourceforge.net>
 119 and Peter O'Gorman <ogorman@users.sourceforge.net>.
 120 .Pp
 121 In Mac OS X 10.4, dlopen was rewritten to be a native part of dyld.
 122 .Pp
 123 .Sh SEE ALSO
 124 .Xr dlclose 3
 125 .Xr dlsym 3
 126 .Xr dlerror 3
 127 .Xr dyld 3
 128 .Xr ld 1