| 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)
- create a new file from a dynamic object component of the calling process
#include <dlfcn.h>intdldump(const char *ipath,const char *opath,intflags);
Thedldump() function creates a new dynamic objectopath from an existingdynamic objectipath that is bound to the current process. Anipath valueof0 is interpreted as the dynamic object that started the process. Thenew object is constructed from the existing objects' disc file. Relocations can beapplied to the new object to pre-bind it to other dynamic objects, orfix the object to a specific memory location. In addition, data elements withinthe new object can be obtained from the objects' memory image asthis data exists in the calling process.
These techniques allow the new object to be executed with a lowerstartup cost. This reduction can be because of less relocations being required to loadthe object, or because of a reduction in the data processing requirements ofthe object. However, limitations can exist in using these techniques. The application ofrelocations to the new dynamic objectopath can restrict its flexibility within adynamically changing environment. In addition, limitations in regards to data usage can makedumping a memory image impractical. SeeEXAMPLES.
The runtime linker verifies that the dynamic objectipath is mapped as partof the current process. Thus, the object must either be the dynamic objectthat started the process, one of the process's dependencies, or an object thathas been preloaded. Seeexec(2), andld.so.1(1).
As part of the runtime processing of a dynamic object,relocation recordswithin the object are interpreted and applied to offsets within the object. Theseoffsets are said to berelocated. Relocations can be categorized into two basictypes:non-symbolic andsymbolic.
Thenon-symbolic relocation is a simplerelative relocation that requires the baseaddress at which the object is mapped to perform the relocation. Thesymbolicrelocation requires the address of an associated symbol, and results in abindingto the dynamic object that defines this symbol. The symbol definition can originatefrom any of the dynamic objects that make up the process, that is,the object that started the process, one of the process's dependencies, an objectthat has been preloaded, or the dynamic object being relocated.
Theflags parameter controls the relocation processing and other attributes of producing thenew dynamic objectopath. Without anyflags, the new object is constructed solely fromthe contents of theipath disc file without any relocations applied.
Various relocation flags can beor'ed into theflags parameter to affectthe relocations that are applied to the new object.Non-symbolic relocations can beapplied using the following:
Relocation records from the objectipath, that definerelative relocations, are applied to the objectopath.
A variety ofsymbolic relocations can be applied using the following flags (eachof these flags also impliesRTLD_REL_RELATIVE is in effect):
Symbolic relocations that result in bindingipath to the dynamic object that started the process, commonly a dynamic executable, are applied to the objectopath.
Symbolic relocations that result in bindingipath to any of the dynamic dependencies of the process are applied to the objectopath.
Symbolic relocations that result in bindingipath to any objects preloaded with the process are applied to the objectopath. SeeLD_PRELOAD inld.so.1(1).
Symbolic relocations that result in bindingipath to itself, are applied to the objectopath.
Weak relocations that remain unresolved are applied to the objectopath as0.
All relocation records defined in the objectipath are applied to the new objectopath. This is basically a concatenation of all the above relocation flags.
Note that for dynamic executables,RTLD_REL_RELATIVE,RTLD_REL_EXEC, andRTLD_REL_SELF have no effect. SeeEXAMPLES.
If relocations, knowledgeable of the base address of the mapped object, are appliedto the new objectopath, then the new object becomes fixed to thelocation that theipath image is mapped within the current process.
Any relocations applied to the new objectopath will have the original relocationrecord removed so that the relocation will not be applied more than once.Otherwise, the new objectopath will retain the relocation records as they existin theipath disc file.
The following additional attributes for creating the new dynamic objectopath canbe specified using theflags parameter:
The new objectopath is constructed from the current memory contents of theipath image as it exists in the calling process. This option allows data modified by the calling process to be captured in the new object. Note that not all data modifications may be applicable for capture; significant restrictions exist in using this technique. SeeEXAMPLES. By default, when processing a dynamic executable, any allocated memory that follows the end of the data segment is captured in the new object (seemalloc(3C) andbrk(2)). This data, which represents the process heap, is saved as a new.SUNW_heap section in the objectopath. The objects' program headers and symbol entries, such as_end, are adjusted accordingly. See alsoRTLD_NOHEAP. When using this attribute, any relocations that have been applied to theipath memory image that do not fall into one of the requested relocation categories are undone, that is, the relocated element is returned to the value as it existed in theipath disc file.
Only collect allocatable sections within the objectopath. Sections that are not part of the dynamic objects' memory image are removed.RTLD_STRIP reduces the size of theopath disc file and is comparable to having run the new object throughstrip(1).
Do not save any heap to the new object. This option is only meaningful when processing a dynamic executable with theRTLD_MEMORY attribute and allows for reducing the size of theopath disc file. The executable must confine its data initialization to data elements within its data segment, and must not use any allocated data elements that comprise the heap.
It should be emphasized, that an object created bydldump() is simply anupdated ELF object file. No additional state regarding the process at the timedldump() is called is maintained in the new object.dldump() does not provide apanacea for checkpoint and resume. A new dynamic executable, for example, will notstart where the original executable calleddldump(). It will gain control at theexecutable's normal entry point. SeeEXAMPLES.
On successful creation of the new object,dldump() returns0. Otherwise, anon-zero value is returned and more detailed diagnostic information is available throughdlerror().
Example 1 Sample code usingdldump().
The following code fragment, which can be part of a dynamic executablea.out, can be used to create a new shared object from oneof the dynamic executables' dependencieslibfoo.so.1:
const char * ipath = "libfoo.so.1";const char * opath = "./tmp/libfoo.so.1";...if (dldump(ipath, opath, RTLD_REL_RELATIVE) != 0) (void) printf("dldump failed: %s\n", dlerror( ));The new shared objectopath is fixed to the address of the mappedipath bound to the dynamic executablea.out. All relative relocations are appliedto this new shared object, which will reduce its relocation overhead when itis used as part of another process.
By performing only relative relocations, any symbolic relocation records remain defined within thenew object, and thus the dynamic binding to external symbols will be preservedwhen the new object is used.
Use of the other relocation flags can fix specific relocations in the newobject and thus can reduce even more the runtime relocation startup cost ofthe new object. However, this will also restrict the flexibility of using thenew object within a dynamically changing environment, as it will bind the newobject to some or all of the dynamic objects presently mapped aspart of the process.
For example, the use ofRTLD_REL_SELF will cause any references to symbols fromipath to be bound to definitions within itself if no other preceding objectdefined the same symbol. In other words, a call tofoo( ) withinipathwill bind to the definitionfoo within the same object. Therefore,opath willhave one less binding that must be computed at runtime. This reduces thestartup cost of usingopath by other applications; however, interposition of the symbolfoowill no longer be possible.
Using a dumped shared object with applied relocations as an applications dependency normallyrequires that the application have the same dependencies as the application that producedthe dumped image. Dumping shared objects, and the various flags associated with relocationprocessing, have some specialized uses. However, the technique is intended as a buildingblock for future technology.
The following code fragment, which is part of the dynamic executablea.out,can be used to create a new version of the dynamic executable:
static char * dumped = 0;const char * opath = "./a.out.new";...if (dumped == 0) { char buffer[100]; int size; time_t seconds; ... /* Perform data initialization */ seconds = time((time_t *)0); size = cftime(buffer, (char *)0, &seconds); if ((dumped = (char *)malloc(size + 1)) == 0) { (void) printf("malloc failed: %s\n", strerror(errno)); return (1); } (void) strcpy(dumped, buffer); ... /* * Tear down any undesirable data initializations and * dump the dynamic executables memory image. */ _exithandle( ); _exit(dldump(0, opath, RTLD_MEMORY));}(void) printf("Dumped: %s\n", dumped);Any modifications made to the dynamic executable, up to the point thedldump() call is made, are saved in the new objecta.out.new. This mechanismallows the executable to update parts of its data segment and heap priorto creating the new object. In this case, the date the executable isdumped is saved in the new object. The new object can thenbe executed without having to carry out the same (presumably expensive) initialization.
For greatest flexibility, this example does not saveany relocated information. The elementsof the dynamic executableipath that have been modified by relocations at processstartup, that is, references to external functions, are returned to the values ofthese elements as they existed in theipath disc file. This preservation of relocationrecords allows the new dynamic executable to be flexible, and correctly bind andinitialize to its dependencies when executed on the same or newer upgrades ofthe OS.
Fixing relocations by applying some of the relocation flags would bind the newobject to the dependencies presently mapped as part of the process callingdldump().It may also remove necessary copy relocation processing required for the correct initializationof its shared object dependencies. Therefore, if the new dynamic executables' dependencies haveno specialized initialization requirements, the executable may still only interact correctly with the dependenciesto which it binds if they were mapped to the same locations asthey were whendldump() was called.
Note that for dynamic executables,RTLD_REL_RELATIVE,RTLD_REL_EXEC, andRTLD_REL_SELF have no effect, asrelocations within the dynamic executable will have been fixed when it was createdbyld(1).
WhenRTLD_MEMORY is used, care should be taken to insure that dumped datasections that reference external objects are not reused without appropriate re-initialization. For example,if a data item contains a file descriptor, a variable returned from ashared object, or some other external data, and this data item has beeninitialized prior to thedldump() call, its value will have no meaningin the new dumped image.
WhenRTLD_MEMORY is used, any modification to a data item that is initializedvia a relocation whose relocation record will be retained in the new imagewill effectively be lost or invalidated within the new image. For example, ifa pointer to an external object is incremented prior to thedldump() call,this data item will be reset to its disc file contents so thatit can be relocated when the new image is used; hence, the previousincrement is lost.
Non-idempotent data initializations may prevent the use ofRTLD_MEMORY. For example, theaddition of elements to a linked-list viainit sections can result inthe linked-list data being captured in the new image. Running this new imagemay result ininit sections continuing to add new elements to the listwithout the prerequisite initialization of the list head. It is recommended that_exithandle(3C)be called beforedldump() to tear down any data initializations established viainitialization code. Note that this may invalidate the calling image; thus, followingthe call todldump(), only a call to_Exit(2) should be made.
Thedldump() function is one of a family of functions that give theuser direct access to the dynamic linking facilities. These facilities are available todynamically-linked processes only. SeeLinker and Libraries Guide).
Seeattributes(5) for descriptions of the following attributes:
|
ld(1),ld.so.1(1),strip(1),_Exit(2),brk(2),exec(2),_exithandle(3C),dladdr(3C),dlclose(3C),dlerror(3C),dlopen(3C),dlsym(3C),end(3C),malloc(3C),attributes(5)
These functions are available to dynamically-linked processes only.
AnyNOBITS sections within theipath are expanded toPROGBITS sections within theopath.NOBITS sections occupy no space within an ELF file image.NOBITS sectionsdeclare memory that must be created and zero-filled when the object is mappedinto the runtime environment..bss is a typical example of this sectiontype.PROGBITS sections, on the other hand, hold information defined by the objectwithin the ELF file image. This section conversion reduces the runtime initialization costof the new dumped object but increases the objects' disc space requirement.
When a shared object is dumped, and relocations are applied which are knowledgeableof the base address of the mapped object, the new object is fixedto this new base address. The dumped object has its ELF type reclassifiedto be a dynamic executable. The dumped object can be processed by theruntime linker, but is not valid as input to the link-editor.
If relocations are applied to the new object, any remaining relocation records arereorganized for better locality of reference. The relocation sections are renamed to.SUNW_relocand the association with the section to relocate, is lost. Only the offsetof the relocation record is meaningful..SUNW_reloc relocations do not make the new objectinvalid to either the runtime linker or link-editor, but can reduce the objectsanalysis with some ELF readers.
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |