| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 3: Basic Library Functions Oracle Solaris 11 Information Library |
enable_extended_FILE_stdio(3C)
posix_spawnattr_getschedparam(3C)
posix_spawnattr_getschedpolicy(3C)
posix_spawnattr_getsigdefault(3C)
posix_spawnattr_getsigignore_np(3C)
posix_spawnattr_getsigmask(3C)
posix_spawnattr_setschedparam(3C)
posix_spawnattr_setschedpolicy(3C)
posix_spawnattr_setsigdefault(3C)
posix_spawnattr_setsigignore_np(3C)
posix_spawnattr_setsigmask(3C)
posix_spawn_file_actions_addclose(3C)
posix_spawn_file_actions_addclosefrom_np(3C)
posix_spawn_file_actions_adddup2(3C)
posix_spawn_file_actions_addopen(3C)
posix_spawn_file_actions_destroy(3C)
posix_spawn_file_actions_init(3C)
pthread_attr_getdetachstate(3C)
pthread_attr_getinheritsched(3C)
pthread_attr_getschedparam(3C)
pthread_attr_getschedpolicy(3C)
pthread_attr_setdetachstate(3C)
pthread_attr_setinheritsched(3C)
pthread_attr_setschedparam(3C)
pthread_attr_setschedpolicy(3C)
pthread_barrierattr_destroy(3C)
pthread_barrierattr_getpshared(3C)
pthread_barrierattr_setpshared(3C)
pthread_condattr_getpshared(3C)
pthread_condattr_setpshared(3C)
pthread_cond_reltimedwait_np(3C)
pthread_key_create_once_np(3C)
pthread_mutexattr_getprioceiling(3C)
pthread_mutexattr_getprotocol(3C)
pthread_mutexattr_getpshared(3C)
pthread_mutexattr_getrobust(3C)
pthread_mutexattr_setprioceiling(3C)
pthread_mutexattr_setprotocol(3C)
pthread_mutexattr_setpshared(3C)
pthread_mutexattr_setrobust(3C)
pthread_mutex_getprioceiling(3C)
pthread_mutex_reltimedlock_np(3C)
pthread_mutex_setprioceiling(3C)
pthread_rwlockattr_destroy(3C)
pthread_rwlockattr_getpshared(3C)
pthread_rwlockattr_setpshared(3C)
pthread_rwlock_reltimedrdlock_np(3C)
pthread_rwlock_reltimedwrlock_np(3C)
pthread_rwlock_timedrdlock(3C)
pthread_rwlock_timedwrlock(3C)
rctlblk_get_enforced_value(3C)
- gain access to an executable object file
#include <dlfcn.h>#include <link.h>void *dlopen(const char *pathname,intmode);
void *dlmopen(Lmid_tlmid,const char *pathname,intmode);
Thedlopen() function makes an executable object file available to a runningprocess.dlopen() returns to the process ahandle that the process canuse on subsequent calls todlsym(3C),dladdr(3C),dlinfo(3C), anddlclose(3C). The valueof thishandle should not be interpreted in any way by the process.Thepathname argument is the path name of the object to beopened. A path name containing an embedded'/' is interpreted as anabsolute path or relative to the current directory. Otherwise, the set ofsearch paths currently in effect by the runtime linker are used to locatethe specified file. SeeNOTES.
If the object file referenced bydlopen() is not already loaded aspart of the process, then the object file is added to theprocess address space. A handle for this object is created and returnedto the caller. If the object file is already part of theprocess, a handle is also returned to the caller. Multiple references to thesame object result in returning the same handle. A reference count withinthe handle maintains the number of callers. Thedlclose() of a handleresults in decrementing the handles reference count. When the reference count reaches 0the object file is a candidate for unloading. Anyinit section withinan object is called once when the object is loaded. Anyfinisection within an object is called once when the object is unloaded.
Whendlopen() causes an object to be loaded, it also loads anynon-lazy dependencies that are recorded within the object given bypathname. Thesedependencies are searched in the order in which the dependencies were loadedto locate any additional dependencies. This process continues until all the dependencies ofpathname are loaded. This dependency tree is referred to as a group.
If the value ofpathname is0,dlopen() provides ahandle ona set of global symbol objects. These objects consist of the originalprogram image file, any dependencies loaded at program startup, and any objects loadedusingdlopen() with theRTLD_GLOBAL flag. Because the latter set of objectscan change during process execution, the set identified byhandle can alsochange dynamically.
Themode argument describes howdlopen() operates onpathname with respect tothe processing of reference relocations. Themode also affects the scope ofvisibility of the symbols provided bypathname and its dependencies. This visibilitycan affect how the resultinghandle is used.
When an object is loaded, the object can contain references to symbolswhose addresses are not known until the object is loaded. These referencesmust be relocated before the symbols can be accessed. References are categorizedas eitherimmediate orlazy. Immediate references are typically references to data itemsused by the object code. Immediate references include pointers to functions andcalls to functions made from position-dependent shared objects. Lazy references are typicallycalls to global functions that are made from position-independent shared objects.
Lazy references can also be identified asdeferred. See the-zdeferredoption ofld(1). Deferred dependencies are only loaded during process execution, when thefirst binding to a deferred reference is made. These references are unaffectedby themode.
Themode argument governs when non-deferred references take place. Themode argumentcan be one of the following values.
Only immediate symbol references are relocated when the object is first loaded. Lazy references are not relocated until a given function is called for the first time. This value formode should improve performance, since a process might not require all lazy references in any given object. This behavior mimics the normal loading of dependencies during process initialization. SeeNOTES.
All non-deferred relocations are performed when the object is first loaded. This process might waste some processing if relocations are performed for lazy references that are never used. However, this mode ensures that when an object is loaded, all non-deferred symbols that are referenced during execution are available. This behavior mimics the loading of dependencies when the environment variableLD_BIND_NOW is in effect.
See theLinker and Libraries Guide for more information about symbol references.
The visibility of symbols that are available for relocation can be affectedbymode. To specify the scope of visibility for symbols that areloaded with adlopen() call,mode should be a bitwise-inclusive OR withone of the following values:
The object's global symbols are made available for the relocation processing of any other object. In addition, symbol lookup usingdlopen(0,mode) and an associateddlsym() allows objects that are loaded withRTLD_GLOBAL to be searched.
The object's globals symbols are only available for the relocation processing of other objects that include the same group.
The program image file and any objects loaded at program startup havethe modeRTLD_GLOBAL. The modeRTLD_LOCAL is the default mode for anyobjects that are acquired withdlopen(). A local object can be adependency of more then one group. Any object of modeRTLD_LOCAL that isreferenced as a dependency of an object of modeRTLD_GLOBAL is promotedtoRTLD_GLOBAL. In other words, theRTLD_LOCAL mode is ignored.
Any object loaded bydlopen() that requires relocations against global symbols canreference the symbols in anyRTLD_GLOBAL object. Objects of this mode areat least the program image file and any objects loaded at programstartup. A loaded object can also reference symbols from itself, and from anydependencies the object references. However, themode parameter can also be abitwise–inclusiveOR with one of the following values to affect the scopeof symbol availability:
Only symbols from the associated group are made available for relocation. A group is established from the defined object and all the dependencies of that object. A group must be completely self-contained. All dependency relationships between the members of the group must be sufficient to satisfy the relocation requirements of each object that defines the group.
The symbols of the object initiating thedlopen() call are made available to the objects obtained bydlopen(). This option is useful when hierarchicaldlopen() families are created. Although the parent object can supply symbols for the relocation of this object, the parent object is not available todlsym() through the returnedhandle.
Only symbols fromRTLD_GLOBAL objects are made available for relocation.
The default modes fordlopen() are bothRTLD_WORLD andRTLD_GROUP. If anobject is requires additional modes, themode parameter can be the bitwise-inclusiveOR of the required modes together with the default modes.
The following modes provide additional capabilities outside of relocation processing:
The specified object is tagged to prevent its deletion from the address space as part of adlclose().
The specified object is not loaded as part of thedlopen(). However, a validhandle is returned if the object already exists as part of the process address space. Additional modes can be specified as a bitwise–inclusive OR with the present mode of the object and its dependencies. TheRTLD_NOLOAD mode provides a means of querying the presence or promoting the modes of an existing dependency.
The default use of ahandle withdlsym() allows a symbol searchto inspect all objects that are associated with the group of objectsthat are loaded fromdlopen(). Themode parameter can also be abitwise–inclusive OR with the following value to restrict this symbol search:
Use of thishandle withdlsym(), restricts the symbol search to the first object associated with thehandle.
An object can be accessed from a process both with and withoutRTLD_FIRST. Although the object will only be loaded once, two differenthandlesare created to provide for the differentdlsym() requirements.
Thedlmopen() function is identical todlopen(), except that an identifying link-mapID(lmid) is provided. This link-map ID informs the dynamic linking facilitiesupon which link-map list to load the object. See theLinker and Libraries Guide fordetails about link-maps.
Thelmid passed todlmopen() identifies the link-map list on which theobject is loaded. This parameter can be any validLmid_t returned bydlinfo() or one of the following special values:
Load the object on the applications link-map list.
Load the object on the dynamic linkers (ld.so.1) link-map list.
Cause the object to create a new link-map list as part of loading. Objects that are opened on a new link-map list must express all of their dependencies.
Thedlopen() function returnsNULL ifpathname cannot be found, cannot beopened for reading, or is not a shared object or a relocatableobject.dlopen() also returnsNULL if an error occurs during the process ofloadingpathname or relocating its symbolic references. SeeNOTES. Additional diagnostic informationis available throughdlerror().
Thedlopen() anddlmopen() functions are members of a family of functionsthat give the user direct access to the dynamic linking facilities. Thisfamily of functions is available only to dynamically-linked processes. See theLinker and Libraries Guide.
Seeattributes(5) for descriptions of the following attributes:
|
ld(1),ld.so.1(1),dladdr(3C),dlclose(3C),dldump(3C),dlerror(3C),dlinfo(3C),dlsym(3C),attributes(5),standards(5)
Ifpathname has dependencies on other objects, these objects are automatically loadedbydlopen(). The directory search path used to findpathname and anydependencies can be affected by setting the environment variableLD_LIBRARY_PATH. AnyLD_LIBRARY_PATHvariable is analyzed once at process startup. The search path can alsobe affected from a runpath setting within the object from which thecall todlopen() originates. These search rules will only be applied to pathnames that do not contain an embedded'/'. Objects whose names resolveto the same absolute path name or relative path name can beopened any number of times usingdlopen(). However, the object that isreferenced will only be loaded once into the address space of the currentprocess.
When loading shared objects, the application should open a specific version ofthe shared object. Do not rely on the version of the sharedobject pointed to by the symbolic link.
When building objects to be loaded on a new link-map list, someprecautions need to be taken. In general, all dependencies must be includedwhen building an object. Also, include/usr/lib/libmapmalloc.so.1 before/lib/libc.so.1 when building anobject.
When an object is loaded on a new link-map list, the objectis isolated from the main running program. Certain global resources are onlyusable from one link-map list. A few examples are thesbrk() basedmalloc(),libthread(), and the signal vectors. Care must be taken not to useany of these resources other than from the primary link-map list. Theseissues are discussed in further detail in theLinker and Libraries Guide.
Some symbols defined in dynamic executables or shared objects can not beavailable to the runtime linker. The symbol table created byld foruse by the runtime linker might contain only a subset of thesymbols that are defined in the object.
As part of loading a new object, initialization code within the objectis calledbefore thedlopen() returns. This initialization is user code, andas such, can produce errors that can not be caught bydlopen().For example, an object loaded usingRTLD_LAZY that attempts to call a functionthat can not be located results in process termination. Erroneous programming practiceswithin the initialization code can also result in process termination. The runtimelinkers debugging facility can offer help identifying these types of error. See theLD_DEBUG environment variable ofld.so.1(1).
Loading relocatable objects is an expensive operation that requires converting the relocatableobject into a shared object memory image. This capability may be usefulin a debugging environment, but is not recommended for production software.
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |