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 13examines the mach-o file specified by 14.Fa path . 15If the file is compatible with the current process and has not already been 16loaded into the current process, it is loaded and linked. After being linked, 17if it contains any initializer functions, they are called, before 18.Fn dlopen 19returns. 20.Fn dlopen 21can load dynamic libraries and bundles. It returns a handle that can 22be used with 23.Fn dlsym 24and 25.Fn dlclose . 26A second call to 27.Fn dlopen 28with the same path will return the same handle, but the internal reference 29count for the handle will be incremented. Therefore all 30.Fn dlopen 31calls should be balanced with a 32.Fn dlclose 33call. 34.Pp 35If a null pointer is passed in 36.Fa path , 37.Fn dlopen 38returns a handle equivalent to RTLD_DEFAULT. 39.Pp 40.Fa mode 41contains options to 42.Fn dlopen . 43It 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 47Each external function reference is bound the first time the function is called. 48.It Dv RTLD_NOW 49All external function references are bound immediately during the call to 50.Fn dlopen . 51.El 52.Pp 53.Dv RTLD_LAZY 54is normally preferred, for reasons of efficiency. 55However, 56.Dv RTLD_NOW 57is useful to ensure that any undefined symbols are discovered during the 58call to 59.Fn dlopen . 60If neither 61RTLD_LAZY nor RTLD_NOW is specified, the default is RTLD_LAZY. 62.Pp 63One of the following flags may be ORed into the 64.Fa mode 65argument: 66.Bl -tag -width RTLD_LOCALX 67.It Dv RTLD_GLOBAL 68Symbols exported from this image (dynamic library or bundle) will be available to any 69images build with -flat_namespace option to 70.Xr ld 1 71or to calls to 72.Fn dlsym 73when using a special handle. 74.It Dv RTLD_LOCAL 75Symbols exported from this image (dynamic library or bundle) are generally hidden 76and only availble to 77.Fn dlsym 78when directly using the handle returned by this call to 79.Fn dlopen . 80.Pp 81.El 82If neither 83RTLD_GLOBAL nor RTLD_LOCAL is specified, the default is RTLD_GLOBAL. 84.Pp 85One of the following may be ORed into the 86.Fa mode 87argument: 88.Bl -tag -width RTLD_NODELETEX 89.It Dv RTLD_NOLOAD 90The specified image is not loaded. However, a valid 91.Fa handle 92is returned if the image already exists in the process. This provides a way 93to query if an image is already loaded. The 94.Fa handle 95returned is ref-counted, so you eventually need a corresponding call to 96.Fn dlclose 97.It Dv RTLD_NODELETE 98The specified image is tagged so that will never be removed from the address space, 99even after all clients have released it via 100.Fn dlclose 101.El 102.Pp 103Additionally, the following may be ORed into the 104.Fa mode 105argument: 106.Bl -tag -width RTLD_FIRSTX 107.It Dv RTLD_FIRST 108The retuned 109.Fa handle 110is tagged so that any 111.Fn dlsym 112calls on the 113.Fa handle 114will only search the image specified, and not subsequent images. If 115.Fa path 116is NULL and the option RTLD_FIRST is used, the 117.Fa handle 118returned will only search the main executable. 119.El 120.Sh SEARCHING 121.Fn dlopen 122searches for a compatible Mach-O file in the directories specified by a set of environment variables and 123the process's current working directory. 124When set, the environment variables contain a colon-separated list of directory paths, 125which can be absolute or relative to the current working directory. 126.Pp 127When 128.Fa path 129does not contain a slash character (i.e. it is just a leaf name), 130.Fn dlopen 131searches 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 134When 135.Fa path 136looks like a framework path (e.g. /stuff/foo.framework/foo), 137.Fn dlopen 138searches 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 148When 149.Fa path 150contains a slash but is not a framework path (i.e. a full path or a partial path to a dylib), 151.Fn dlopen 152searches 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 162Note: If DYLD_FALLBACK_LIBRARY_PATH is not set, dlopen operates as if 163DYLD_FALLBACK_LIBRARY_PATH was set to $HOME/lib:/usr/local/lib:/usr/lib. 164.Pp 165Note: If DYLD_FALLBACK_FRAMEWORK_PATH is not set, dlopen operates as if 166DYLD_FALLBACK_FRAMEWORK_PATH was set to $HOME/Library/Frameworks:/Library/Frameworks:/Network/Library/Frameworks:/System/Library/Frameworks. 167.Pp 168Note: There are no configuration files to control dlopen searching. 169.Pp 170Note: If the main executable is a set[ug]id binary or codesigned with entitlements, 171then all environment variables are ignored, and only a full path can be used. 172.Pp 173Note: 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 176If 177.Fn dlopen 178fails, 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 188