doc/man/man3/dlopen.3

   1 .Dd Aug 7, 2012
   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_LOCALX
  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 .Pp
  81 .El
  82 If neither
  83 RTLD_GLOBAL nor RTLD_LOCAL is specified, the default is RTLD_GLOBAL.
  84 .Pp
  85 One of the following may be ORed into the
  86 .Fa mode
  87 argument:
  88 .Bl -tag -width RTLD_NODELETEX
  89 .It Dv RTLD_NOLOAD
  90 The specified image is not loaded.  However, a valid
  91 .Fa handle
  92 is returned if the image already exists in the process. This provides a way
  93 to query if an image is already loaded.  The
  94 .Fa handle
  95 returned is ref-counted, so you eventually need a corresponding call to
  96 .Fn dlclose
  97 .It Dv RTLD_NODELETE
  98 The specified image is tagged so that will never be removed from the address space,
  99 even after all clients have released it via
 100 .Fn dlclose
 101 .El
 102 .Pp
 103 Additionally, the following may be ORed into the
 104 .Fa mode
 105 argument:
 106 .Bl -tag -width RTLD_FIRSTX
 107 .It Dv RTLD_FIRST
 108 The retuned
 109 .Fa handle
 110 is tagged so that any
 111 .Fn dlsym
 112 calls on the
 113 .Fa handle
 114 will only search the image specified, and not subsequent images.  If
 115 .Fa path
 116 is NULL and the option RTLD_FIRST is used, the
 117 .Fa handle
 118 returned will only search the main executable.
 119 .El
 120 .Sh SEARCHING
 121 .Fn dlopen
 122 searches for a compatible Mach-O file in the directories specified by a set of environment variables and
 123 the process's current working directory.
 124 When set, the environment variables contain a colon-separated list of directory paths,
 125 which can be absolute or relative to the current working directory.
 126 .Pp
 127 When
 128 .Fa path
 129 does not contain a slash character (i.e. it is just a leaf name),
 130 .Fn dlopen
 131 searches the following until it finds a compatible Mach-O file: $LD_LIBRARY_PATH,
 132 $DYLD_LIBRARY_PATH, current working directory, $DYLD_FALLBACK_LIBRARY_PATH.
 133 .Pp
 134 When
 135 .Fa path
 136 looks like a framework path (e.g. /stuff/foo.framework/foo),
 137 .Fn dlopen
 138 searches the following until it finds a compatible Mach-O file:
 139 $DYLD_FRAMEWORK_PATH (with framework partial path from
 140 .Fa path
 141 ), then the supplied
 142 .Fa path
 143 (using current working directory for relative paths), then
 144 $DYLD_FALLBACK_FRAMEWORK_PATH (with framework partial path from
 145 .Fa path
 146 ).
 147 .Pp
 148 When
 149 .Fa path
 150 contains a slash but is not a framework path (i.e. a full path or a partial path to a dylib),
 151 .Fn dlopen
 152 searches the following until it finds a compatible Mach-O file:
 153 $DYLD_LIBRARY_PATH (with leaf name from
 154 .Fa path
 155 ), then the supplied
 156 .Fa path
 157 (using current working directory for relative paths), then
 158 $DYLD_FALLBACK_LIBRARY_PATH (with leaf name from
 159 .Fa path
 160 ).
 161 .Pp
 162 Note: If DYLD_FALLBACK_LIBRARY_PATH is not set, dlopen operates as if
 163 DYLD_FALLBACK_LIBRARY_PATH was set to $HOME/lib:/usr/local/lib:/usr/lib.
 164 .Pp
 165 Note: If DYLD_FALLBACK_FRAMEWORK_PATH is not set, dlopen operates as if
 166 DYLD_FALLBACK_FRAMEWORK_PATH was set to $HOME/Library/Frameworks:/Library/Frameworks:/Network/Library/Frameworks:/System/Library/Frameworks.
 167 .Pp
 168 Note: There are no configuration files to control dlopen searching.
 169 .Pp
 170 Note: If the main executable is a set[ug]id binary or codesigned with entitlements,
 171 then all environment variables are ignored, and only a full path can be used.
 172 .Pp
 173 Note: Mac OS X uses "universal" files to combine 32-bit and 64-bit libraries.  This means there are no separate 32-bit and 64-bit search paths.
 174 .Pp
 175 .Sh RETURN VALUES
 176 If
 177 .Fn dlopen
 178 fails, it returns a null pointer, and sets an error condition which may be interrogated with
 179 .Fn dlerror .
 180 .Pp
 181 .Sh SEE ALSO
 182 .Xr dlopen_preflight 3
 183 .Xr dlclose 3
 184 .Xr dlsym 3
 185 .Xr dlerror 3
 186 .Xr dyld 1
 187 .Xr ld 1