svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
dldump(3c)
Standard C Library Functions dldump(3C)
NAME
dldump - create a new file from a dynamic object component of the call‐
ing process
SYNOPSIS
#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 exist‐
ing 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' disk
file.
These techniques allow the new object to be executed with a lower
startup cost. This reduction can be because of a reduction in the data
processing requirements of the object. However, limitations in regards
to data usage can make dumping a memory image impractical. See EXAM‐
PLES.
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, one of the process's dependen‐
cies, or an object that has been preloaded. See exec(2), and
ld.so.1(1).
The flags parameter controls attributes of producing the new dynamic
object opath. Without any flags, the new object is constructed solely
from the contents of the ipath disk file.
The following attributes for creating the new dynamic object opath can
be specified using the flags parameter:
RTLD_MEMORY
The new object opath is constructed from the current memory con‐
tents 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 processing 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 head‐
ers 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 are undone, that is,
the relocated element is returned to the value as it existed in the
ipath disk file.
RTLD_STRIP
Only collect allocatable sections within the object opath. Sections
that are not part of the dynamic objects' memory image are removed.
RTLD_STRIP reduces the size of the opath disk file and is compara‐
ble to having run the new object through strip(1).
RTLD_NOHEAP
Do not save any heap to the new object. This option is only mean‐
ingful when processing a dynamic executable with the RTLD_MEMORY
attribute and allows for reducing the size of the opath disk file.
The executable must confine its data initialization to data ele‐
ments 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 and resume. A new
dynamic executable, for example, will not start where the original exe‐
cutable called dldump(). It will gain control at the executable's nor‐
mal entry point. See EXAMPLES.
RETURN VALUES
On successful creation of the new object, dldump() returns 0. Other‐
wise, a non-zero value is returned and more detailed diagnostic infor‐
mation is available through dlerror().
EXAMPLES
Example 1 Sample code using dldump().
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 = NULL;
const char *opath = "./a.out.new";
...
if (dumped == NULL) {
char buffer[100];
int size;
time_t seconds;
...
/* Perform data initialization */
seconds = time(NULL);
size = cftime(buffer, NULL, &seconds);
if ((dumped = malloc(size + 1)) == NULL) {
(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 object. In this case, the date the exe‐
cutable 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.
The elements of the dynamic executable ipath that have been modified by
relocations at process startup, that is, references to external func‐
tions, are returned to the values of these elements as they existed in
the ipath disk file. This preservation of relocation records allows the
new dynamic executable to be flexible, and correctly bind and initial‐
ize to its dependencies when executed on the same or newer upgrades of
the OS.
When RTLD_MEMORY is used, care should be taken to ensure 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 variable 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 ini‐
tialized 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 disk
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 sec‐
tions can result in the linked-list 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 established via initial‐
ization code. Note that this may invalidate 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 facilities. These facilities
are available to dynamically-linked processes only. See the Oracle
Solaris 11.4 Linkers and Libraries Guide).
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ MT-LevelMT-Safe
SEE ALSO
ld(1), ld.so.1(1), strip(1), _Exit(2), brk(2), exec(2), dlsym(3C),
_exithandle(3C), dladdr(3C), dlclose(3C), dlerror(3C), dlopen(3C),
end(3C), malloc(3C), attributes(7)
Oracle Solaris 11.4 Linkers and Libraries Guide
NOTES
These functions are available to dynamically-linked processes only.
Any NOBITS sections within the ipath are expanded to PROGBITS sections
within the opath. NOBITS sections occupy no space within an ELF file
image. NOBITS sections 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 initialization cost of the
new dumped object but increases the objects' disk space requirement.
Oracle Solaris 11.4 discontinued support for the following dldump()
flags, which enabled various forms of relocation processing:
RTLD_REL_RELATIVE, RTLD_REL_EXEC, RTLD_REL_DEPENDS, RTLD_REL_PRELOAD,
RTLD_REL_SELF, RTLD_REL_WEAK, and RTLD_REL_ALL. An attempt to use any
of these flags will cause dldump() to report an error by returning a
non-zero value.
Oracle Solaris 11.4 11 May 2021 dldump(3C)