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