SunOS man pages : dldump (3)
Dynamic Linking Library Functions dldump(3DL)
NAME
dldump - create a new file from a dynamic object component
of the calling process
SYNOPSIS
cc [ flag ... ] file ... -ldl [ library ... ]
#include <dlfcn.h>
int dldump(const char * ipath, const char * opath, int
flags);
DESCRIPTION
The dldump() function creates a new dynamic object opath
from an existing dynamic object ipath that is bound to the
current process. An ipath value of 0 is interpreted as the
dynamic object that started the process. The new object is
constructed from the existing objects' disc file. Reloca-
tions can be applied to the new object to pre-bind it to
other dynamic objects, or fix the object to a specific
memory location. In addition, data elements within the new
object may be obtained from the objects' memory image as it
exists in the calling process.
These techniques allow the new object to be executed with a
lower startup cost, either because there are less reloca-
tions required to load the object, or because of a reduction
in the data processing requirements of the object. However,
it is important to note that limitations may exist in using
these techniques. Applying relocations to the new dynamic
object opath may restrict its flexibility within a dynami-
cally changing environment. In addition, limitations regard-
ing data usage may make dumping a memory image impractical
(see EXAMPLES).
The runtime linker verifies that the dynamic object ipath is
mapped as part of the current process. Thus, the object must
either be the dynamic object that started the process (see
exec(2)), one of the process's dependencies, or an object
that has been preloaded (see ld.so.1(1)).
As part of the runtime processing of a dynamic object, relo-
cation records within the object are interpreted and applied
to offsets within the object. These offsets are said to be
relocated. Relocations can be categorized into two basic
types: non-symbolic and symbolic.
The non-symbolic relocation is a simple relative relocation
that requires the base address at which the object is mapped
to perform the relocation. The symbolic relocation requires
the address of an associated symbol, and results in a bind-
ing to the dynamic object that defines this symbol. This
symbol definition may originate from any of the dynamic
SunOS 5.8 Last change: 2 Sept 1999 1
Dynamic Linking Library Functions dldump(3DL)
objects that make up the process, that is, the object that
started the process, one of the process's dependencies, an
object that has been preloaded, or the dynamic object being
relocated.
The flags parameter controls the relocation processing and
other attributes of producing the new dynamic object opath.
Without any flags, the new object is constructed solely from
the contents of the ipath disc file without any relocations
applied.
Various relocation flags may be or'ed into the flags parame-
ter to affect the relocations applied to the new object.
Non-symbolic relocations can be applied using the following:
RTLD_REL_RELATIVE
Relocation records from the object ipath, that define
relative relocations, are applied to the object opath.
A variety of symbolic relocations can be applied using the
following flags (each of these flags also implies
RTLD_REL_RELATIVE is in effect):
RTLD_REL_EXEC
Symbolic relocations that result in binding ipath to
the dynamic object that started the process (commonly
a dynamic executable) are applied to the object opath.
RTLD_REL_DEPENDS
Symbolic relocations that result in binding ipath to
any of the dynamic dependencies of the process are
applied to the object opath.
RTLD_REL_PRELOAD
Symbolic relocations that result in binding ipath to
any objects preloaded with the process are applied to
the object opath. (See LD_PRELOAD in ld.so.1(1)).
RTLD_REL_SELF
Symbolic relocations that result in binding ipath to
itself are applied to the object opath.
RTLD_REL_WEAK
Weak relocations that remain unresolved are applied to
the object opath as 0.
RTLD_REL_ALL
All relocation records defined in the object ipath are
applied to the new object opath (this is basically a
concatenation of all the above relocation flags).
SunOS 5.8 Last change: 2 Sept 1999 2
Dynamic Linking Library Functions dldump(3DL)
Note that for dynamic executables, RTLD_REL_RELATIVE,
RTLD_REL_EXEC, and RTLD_REL_SELF have no effect (see EXAM-
PLES).
If relocations, knowledgeable of the base address of the
mapped object, are applied to the new object opath, then the
new object will become fixed to the location that the ipath
image is mapped within the current process.
Any relocations applied to the new object opath will have
the original relocation record removed so that the reloca-
tion will not be applied more than once. Otherwise, the new
object opath will retain the relocation records as they
exist in the ipath disc file.
The following additional attributes for creating the new
dynamic object opath can be specified using the flags param-
eter:
RTLD_MEMORY
The new object opath is constructed from the current
memory contents of the ipath 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 (see EXAMPLES). By default, when pro-
cessing a dynamic executable, any allocated memory
that follows the end of the data segment is captured
in the new object (see malloc (3C) and brk(2)). This
data, which represents the process heap, is saved as a
new .SUNW_heap section in the object opath. The
objects' program headers and symbol entries, such as
_end, are adjusted accordingly. See also RTLD_NOHEAP.
When using this attribute, any relocations that have
been applied to the ipath 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 the ipath disc file.
RTLD_STRIP
Only collect allocatable sections within the object
opath; sections that are not part of the dynamic
objects' memory image are removed. This parameter
reduces the size of the opath disc file and is compar-
able to having run the new object through strip(1).
RTLD_NOHEAP
Do not save any heap to the new object. This option is
only meaningful when processing a dynamic executable
with the RTLD_MEMORY attribute and allows for reducing
the size of the opath disc file. In this case, the
SunOS 5.8 Last change: 2 Sept 1999 3
Dynamic Linking Library Functions dldump(3DL)
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 by dldump()
is simply an updated ELF object file. No additional state
regarding the process at the time dldump() is called is
maintained in the new object. dldump() does not provide a
panacea for checkpoint/resume. A new dynamic executable, for
example, will not start where the original executable called
dldump(); it will gain control at the executable's normal
entry point (see EXAMPLES).
RETURN VALUES
On successful creation of the new object, dldump() returns
0. Otherwise, a non-zero value is returned and more detailed
diagnostic information is available through dlerror().
EXAMPLES
Example 1: Sample code using dldump().
The following code fragment, which can be part of a dynamic
executable a.out, can be used to create a new shared object
from one of the dynamic executables' dependencies
libfoo.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 object opath is fixed to the address of the
mapped ipath bound to the dynamic executable a.out. All
relative relocations are applied to this new shared object,
which will reduce its relocation overhead when it is used as
part of another process.
By performing only relative relocations, any symbolic relo-
cation records remain defined within the new object, and
thus the dynamic binding to external symbols will be
preserved when the new object is used.
Use of the other relocation flags can fix specific reloca-
tions in the new object and thus can reduce even more the
runtime relocation startup cost of the new object. However,
this will also restrict the flexibility of using the new
object within a dynamically changing environment, as it will
bind the new object to some or all of the dynamic objects
presently mapped as part of the process.
SunOS 5.8 Last change: 2 Sept 1999 4
Dynamic Linking Library Functions dldump(3DL)
For example, the use of RTLD_REL_SELF will cause any refer-
ences to symbols from ipath to be bound to definitions
within itself if no other preceding object defined the same
symbol. In other words, a call to foo() within ipath will
bind to the definition foo within the same object. There-
fore, opath will have one less binding that must be computed
at runtime. This reduces the startup cost of using opath by
other applications; however, interposition of the symbol foo
will no longer be possible.
Using a dumped shared object with applied relocations as an
applications dependency normally requires that the applica-
tion have the same dependencies as the application that pro-
duced the dumped image. Dumping shared objects, and the
various flags associated with relocation processing, have
some specialized uses. However, the technique is intended as
a building block for future technology.
The following code fragment, which is part of the dynamic
executable a.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 the dldump() call is made, are saved in the new object
a.out.new. This mechanism allows the executable to update
parts of its data segment and heap prior to creating the new
SunOS 5.8 Last change: 2 Sept 1999 5
Dynamic Linking Library Functions dldump(3DL)
object. In this case, the date the executable is dumped is
saved in the new object. The new object can then be executed
without having to carry out the same (presumably expensive)
initialization.
For greatest flexibility, this example does not save any
relocated information. The elements of the dynamic execut-
able ipath that have been modified by relocations at process
startup, that is, references to external functions, are
returned to the values of these elements as they existed in
the ipath disc file. This preservation of relocation records
allows the new dynamic executable to be flexible, and
correctly bind and initialize to its dependencies when exe-
cuted on the same or newer upgrades of the OS.
Fixing relocations by applying some of the relocation flags
would bind the new object to the dependencies presently
mapped as part of the process calling dldump(). It may also
remove necessary copy relocation processing required for the
correct initialization of its shared object dependencies.
Therefore, if the new dynamic executables' dependencies have
no specialized initialization requirements, the executable
may still only interact correctly with the dependencies to
which it binds if they were mapped to the same locations as
they were when dldump() was called.
Note that for dynamic executables, RTLD_REL_RELATIVE,
RTLD_REL_EXEC, and RTLD_REL_SELF have no effect, as reloca-
tions within the dynamic executable will have been fixed
when it was created by ld(1).
When RTLD_MEMORY is used, care should be taken to insure
that dumped data sections that reference external objects
are not reused without appropriate re-initialization. For
example, if a data item contains a file descriptor, a vari-
able returned from a shared object, or some other external
data, and this data item has been initialized prior to the
dldump() call, its value will have no meaning in the new
dumped image.
When RTLD_MEMORY is used, any modification to a data item
that is initialized via a relocation whose relocation record
will be retained in the new image will effectively be lost
or invalidated within the new image. For example, if a
pointer to an external object is incremented prior to the
dldump() call, this data item will be reset to its disc file
contents so that it can be relocated when the new image is
used; hence, the previous increment is lost.
Non-idempotent data initializations may prevent the use of
RTLD_MEMORY. For example, the addition of elements to a
linked-list via init sections can result in the linked-list
SunOS 5.8 Last change: 2 Sept 1999 6
Dynamic Linking Library Functions dldump(3DL)
data being captured in the new image. Running this new image
may result in init sections continuing to add new elements
to the list without the prerequisite initialization of the
list head. It is recommended that _exithandle(3C) be called
before dldump() to tear down any data initializations esta-
blished via initialization code. Note that this may invali-
date the calling image; thus, following the call to
dldump(), only a call to _exit(2) should be made.
USAGE
The dldump() function is one of a family of functions that
give the user direct access to the dynamic linking facili-
ties (see Linker and Libraries Guide) and are available to
dynamically-linked processes only.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWcsu |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
ld(1), ld.so.1(1), strip(1), _exit(2), brk(2), exec(2),
_exithandle(3C), dladdr(3DL), dlclose(3DL), dlerror(3DL),
dlopen(3DL), dlsym(3DL), end(3C), malloc(3C), attributes(5)
Linker and Libraries Guide
NOTES
These functions are available to dynamically-linked
processes only.
Any NOBITS sections within the ipath are expanded to PROG-
BITS sections within the opath. NOBITS sections occupy no
space within an ELF file image. They declare memory that
must be created and zero-filled when the object is mapped
into the runtime environment. .bss is a typical example of
this section type. PROGBITS sections, on the other hand,
hold information defined by the object within the ELF file
image. This section conversion reduces the runtime initiali-
zation cost of the new dumped object but increases the
objects' disc space requirement.
When a shared object is dumped, and relocations are applied
which are knowledgeable of the base address of the mapped
SunOS 5.8 Last change: 2 Sept 1999 7
Dynamic Linking Library Functions dldump(3DL)
object, the new object is fixed to this new base address and
thus its ELF type is reclassified to be a dynamic execut-
able. This new object can be processed by the runtime
linker, but is not valid as input to the link-editor.
If relocations are applied to the new object, any remaining
relocation records will be reorganized for better locality
of reference. The relocation sections are renamed to
.SUNW_reloc and the association to the section they were to
relocate is lost. Only the offset of the relocation record
itself is meaningful. This change does not make the new
object invalid to either the runtime linker or link-editor,
but may reduce the objects analysis with some ELF readers.
SunOS 5.8 Last change: 2 Sept 1999 8
|
 |
|
|
