dyld-43.tar.gz
[apple/dyld.git] / 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