X-Git-Url: https://git.saurik.com/apple/dyld.git/blobdiff_plain/0959b6d4289bd106fddb7fe7d84a346159895fdd..refs/heads/master:/doc/man/man3/dlopen.3?ds=sidebyside diff --git a/doc/man/man3/dlopen.3 b/doc/man/man3/dlopen.3 index e4ef8f2..1da4927 100644 --- a/doc/man/man3/dlopen.3 +++ b/doc/man/man3/dlopen.3 @@ -1,4 +1,4 @@ -.Dd February 8, 2005 +.Dd Aug 7, 2012 .Os .Dt DLOPEN 3 .Sh NAME @@ -63,7 +63,7 @@ RTLD_LAZY nor RTLD_NOW is specified, the default is RTLD_LAZY. One of the following flags may be ORed into the .Fa mode argument: -.Bl -tag -width RTLD_GLOBALX +.Bl -tag -width RTLD_LOCALX .It Dv RTLD_GLOBAL Symbols exported from this image (dynamic library or bundle) will be available to any images build with -flat_namespace option to @@ -77,52 +77,111 @@ and only availble to .Fn dlsym when directly using the handle returned by this call to .Fn dlopen . +.Pp +.El If neither RTLD_GLOBAL nor RTLD_LOCAL is specified, the default is RTLD_GLOBAL. +.Pp +One of the following may be ORed into the +.Fa mode +argument: +.Bl -tag -width RTLD_NODELETEX +.It Dv RTLD_NOLOAD +The specified image is not loaded. However, a valid +.Fa handle +is returned if the image already exists in the process. This provides a way +to query if an image is already loaded. The +.Fa handle +returned is ref-counted, so you eventually need a corresponding call to +.Fn dlclose +.It Dv RTLD_NODELETE +The specified image is tagged so that will never be removed from the address space, +even after all clients have released it via +.Fn dlclose +.El +.Pp +Additionally, the following may be ORed into the +.Fa mode +argument: +.Bl -tag -width RTLD_FIRSTX +.It Dv RTLD_FIRST +The retuned +.Fa handle +is tagged so that any +.Fn dlsym +calls on the +.Fa handle +will only search the image specified, and not subsequent images. If +.Fa path +is NULL and the option RTLD_FIRST is used, the +.Fa handle +returned will only search the main executable. .El .Sh SEARCHING .Fn dlopen -uses a series of steps to find a compatible mach-o file. The first compatible file found is used. +searches for a compatible Mach-O file in the directories specified by a set of environment variables and +the process's current working directory. +When set, the environment variables contain a colon-separated list of directory paths, +which can be absolute or relative to the current working directory. +.Pp +When +.Fa path +does not contain a slash character (i.e. it is just a leaf name), +.Fn dlopen +searches the following until it finds a compatible Mach-O file: $LD_LIBRARY_PATH, +$DYLD_LIBRARY_PATH, current working directory, $DYLD_FALLBACK_LIBRARY_PATH. .Pp -1) If the directory specified by +When .Fa path -does not contain a slash '/' (i.e. it is a leaf name) then the environment variable LD_LIBRARY_PATH is -used. LD_LIBRARY_PATH should be a colon seperated list of directories. +looks like a framework path (e.g. /stuff/foo.framework/foo), .Fn dlopen -searches each directory, in the order specified, for the leaf name -.Fa path . +searches the following until it finds a compatible Mach-O file: +$DYLD_FRAMEWORK_PATH (with framework partial path from +.Fa path +), then the supplied +.Fa path +(using current working directory for relative paths), then +$DYLD_FALLBACK_FRAMEWORK_PATH (with framework partial path from +.Fa path +). .Pp -2) If DYLD_LIBRARY_PATH is set, then those directories are searched, in order, -with the leaf name of -.Fa path . +When +.Fa path +contains a slash but is not a framework path (i.e. a full path or a partial path to a dylib), +.Fn dlopen +searches the following until it finds a compatible Mach-O file: +$DYLD_LIBRARY_PATH (with leaf name from +.Fa path +), then the supplied +.Fa path +(using current working directory for relative paths), then +$DYLD_FALLBACK_LIBRARY_PATH (with leaf name from +.Fa path +). .Pp -3) If DYLD_FALLBACK_LIBRARY_PATH is set, then those directories are searched, in order -with the leaf name of -.Fa path . -If DYLD_FALLBACK_LIBRARY_PATH is not set, then the following directories are searched: $HOME/lib, /usr/local/lib, /usr/lib +Note: If DYLD_FALLBACK_LIBRARY_PATH is not set, dlopen operates as if +DYLD_FALLBACK_LIBRARY_PATH was set to $HOME/lib:/usr/local/lib:/usr/lib. .Pp -4) Lastly, -.Fa path -is tried as-is as a regular file path. That means it might resolve relative to the current working directory. +Note: If DYLD_FALLBACK_FRAMEWORK_PATH is not set, dlopen operates as if +DYLD_FALLBACK_FRAMEWORK_PATH was set to $HOME/Library/Frameworks:/Library/Frameworks:/Network/Library/Frameworks:/System/Library/Frameworks. .Pp Note: There are no configuration files to control dlopen searching. .Pp -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. +Note: If the main executable is a set[ug]id binary or codesigned with entitlements, +then all environment variables are ignored, and only a full path can be used. +.Pp +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. .Pp .Sh RETURN VALUES If .Fn dlopen fails, it returns a null pointer, and sets an error condition which may be interrogated with .Fn dlerror . -.Sh AUTHORS -Mac OS X 10.3 incorporated the dlcompat package written by Jorge Acereda -and Peter O'Gorman . -.Pp -In Mac OS X 10.4, dlopen was rewritten to be a native part of dyld. .Pp .Sh SEE ALSO +.Xr dlopen_preflight 3 .Xr dlclose 3 .Xr dlsym 3 .Xr dlerror 3 -.Xr dyld 3 +.Xr dyld 1 .Xr ld 1