]> git.saurik.com Git - apple/dyld.git/blob - doc/man/man3/dlopen.3
dyld-655.1.tar.gz
[apple/dyld.git] / 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