1dldump(3C) Standard C Library Functions dldump(3C)
2
3
4
6 dldump - create a new file from a dynamic object component of the call‐
7 ing process
8
10 #include <dlfcn.h>
11
12 int dldump(const char * ipath, const char * opath, int flags);
13
14
16 The dldump() function creates a new dynamic object opath from an exist‐
17 ing dynamic object ipath that is bound to the current process. An ipath
18 value of 0 is interpreted as the dynamic object that started the
19 process. The new object is constructed from the existing objects' disc
20 file. Relocations can be applied to the new object to pre-bind it to
21 other dynamic objects, or fix the object to a specific memory location.
22 In addition, data elements within the new object can be obtained from
23 the objects' memory image as this data exists in the calling process.
24
25
26 These techniques allow the new object to be executed with a lower
27 startup cost. This reduction can be because of less relocations being
28 required to load the object, or because of a reduction in the data pro‐
29 cessing requirements of the object. However, limitations can exist in
30 using these techniques. The application of relocations to the new
31 dynamic object opath can restrict its flexibility within a dynamically
32 changing environment. In addition, limitations in regards to data usage
33 can make dumping a memory image impractical. See EXAMPLES.
34
35
36 The runtime linker verifies that the dynamic object ipath is mapped as
37 part of the current process. Thus, the object must either be the
38 dynamic object that started the process, one of the process's dependen‐
39 cies, or an object that has been preloaded. See exec(2), and
40 ld.so.1(1).
41
42
43 As part of the runtime processing of a dynamic object, relocation
44 records within the object are interpreted and applied to offsets within
45 the object. These offsets are said to be relocated. Relocations can be
46 categorized into two basic types: non-symbolic and symbolic.
47
48
49 The non-symbolic relocation is a simple relative relocation that
50 requires the base address at which the object is mapped to perform the
51 relocation. The symbolic relocation requires the address of an associ‐
52 ated symbol, and results in a binding to the dynamic object that
53 defines this symbol. The symbol definition can originate from any of
54 the dynamic objects that make up the process, that is, the object that
55 started the process, one of the process's dependencies, an object that
56 has been preloaded, or the dynamic object being relocated.
57
58
59 The flags parameter controls the relocation processing and other
60 attributes of producing the new dynamic object opath. Without any
61 flags, the new object is constructed solely from the contents of the
62 ipath disc file without any relocations applied.
63
64
65 Various relocation flags can be or'ed into the flags parameter to
66 affect the relocations that are applied to the new object. Non-symbolic
67 relocations can be applied using the following:
68
69 RTLD_REL_RELATIVE Relocation records from the object ipath, that
70 define relative relocations, are applied to the
71 object opath.
72
73
74
75 A variety of symbolic relocations can be applied using the following
76 flags (each of these flags also implies RTLD_REL_RELATIVE is in
77 effect):
78
79 RTLD_REL_EXEC Symbolic relocations that result in binding ipath
80 to the dynamic object that started the process,
81 commonly a dynamic executable, are applied to the
82 object opath.
83
84
85 RTLD_REL_DEPENDS Symbolic relocations that result in binding ipath
86 to any of the dynamic dependencies of the process
87 are applied to the object opath.
88
89
90 RTLD_REL_PRELOAD Symbolic relocations that result in binding ipath
91 to any objects preloaded with the process are
92 applied to the object opath. See LD_PRELOAD in
93 ld.so.1(1).
94
95
96 RTLD_REL_SELF Symbolic relocations that result in binding ipath
97 to itself, are applied to the object opath.
98
99
100 RTLD_REL_WEAK Weak relocations that remain unresolved are applied
101 to the object opath as 0.
102
103
104 RTLD_REL_ALL All relocation records defined in the object ipath
105 are applied to the new object opath. This is basi‐
106 cally a concatenation of all the above relocation
107 flags.
108
109
110
111 Note that for dynamic executables, RTLD_REL_RELATIVE, RTLD_REL_EXEC,
112 and RTLD_REL_SELF have no effect. See EXAMPLES.
113
114
115 If relocations, knowledgeable of the base address of the mapped object,
116 are applied to the new object opath, then the new object becomes fixed
117 to the location that the ipath image is mapped within the current
118 process.
119
120
121 Any relocations applied to the new object opath will have the original
122 relocation record removed so that the relocation will not be applied
123 more than once. Otherwise, the new object opath will retain the reloca‐
124 tion records as they exist in the ipath disc file.
125
126
127 The following additional attributes for creating the new dynamic object
128 opath can be specified using the flags parameter:
129
130 RTLD_MEMORY The new object opath is constructed from the current
131 memory contents of the ipath image as it exists in the
132 calling process. This option allows data modified by the
133 calling process to be captured in the new object. Note
134 that not all data modifications may be applicable for
135 capture; significant restrictions exist in using this
136 technique. See EXAMPLES. By default, when processing a
137 dynamic executable, any allocated memory that follows
138 the end of the data segment is captured in the new
139 object (see malloc(3C) and brk(2)). This data, which
140 represents the process heap, is saved as a new
141 .SUNW_heap section in the object opath. The objects'
142 program headers and symbol entries, such as _end, are
143 adjusted accordingly. See also RTLD_NOHEAP. When using
144 this attribute, any relocations that have been applied
145 to the ipath memory image that do not fall into one of
146 the requested relocation categories are undone, that is,
147 the relocated element is returned to the value as it
148 existed in the ipath disc file.
149
150
151 RTLD_STRIP Only collect allocatable sections within the object
152 opath. Sections that are not part of the dynamic
153 objects' memory image are removed. RTLD_STRIP reduces
154 the size of the opath disc file and is comparable to
155 having run the new object through strip(1).
156
157
158 RTLD_NOHEAP Do not save any heap to the new object. This option is
159 only meaningful when processing a dynamic executable
160 with the RTLD_MEMORY attribute and allows for reducing
161 the size of the opath disc file. The executable must
162 confine its data initialization to data elements within
163 its data segment, and must not use any allocated data
164 elements that comprise the heap.
165
166
167
168 It should be emphasized, that an object created by dldump() is simply
169 an updated ELF object file. No additional state regarding the process
170 at the time dldump() is called is maintained in the new object.
171 dldump() does not provide a panacea for checkpoint and resume. A new
172 dynamic executable, for example, will not start where the original exe‐
173 cutable called dldump(). It will gain control at the executable's nor‐
174 mal entry point. See EXAMPLES.
175
177 On successful creation of the new object, dldump() returns 0. Other‐
178 wise, a non-zero value is returned and more detailed diagnostic infor‐
179 mation is available through dlerror().
180
182 Example 1 Sample code using dldump().
183
184
185 The following code fragment, which can be part of a dynamic executable
186 a.out, can be used to create a new shared object from one of the
187 dynamic executables' dependencies libfoo.so.1:
188
189
190 const char * ipath = "libfoo.so.1";
191 const char * opath = "./tmp/libfoo.so.1";
192 ...
193 if (dldump(ipath, opath, RTLD_REL_RELATIVE) != 0)
194 (void) printf("dldump failed: %s\n", dlerror());
195
196
197
198 The new shared object opath is fixed to the address of the mapped ipath
199 bound to the dynamic executable a.out. All relative relocations are
200 applied to this new shared object, which will reduce its relocation
201 overhead when it is used as part of another process.
202
203
204
205 By performing only relative relocations, any symbolic relocation
206 records remain defined within the new object, and thus the dynamic
207 binding to external symbols will be preserved when the new object is
208 used.
209
210
211
212 Use of the other relocation flags can fix specific relocations in the
213 new object and thus can reduce even more the runtime relocation startup
214 cost of the new object. However, this will also restrict the flexibil‐
215 ity of using the new object within a dynamically changing environment,
216 as it will bind the new object to some or all of the dynamic objects
217 presently mapped as part of the process.
218
219
220
221 For example, the use of RTLD_REL_SELF will cause any references to sym‐
222 bols from ipath to be bound to definitions within itself if no other
223 preceding object defined the same symbol. In other words, a call to
224 foo() within ipath will bind to the definition foo within the same
225 object. Therefore, opath will have one less binding that must be com‐
226 puted at runtime. This reduces the startup cost of using opath by other
227 applications; however, interposition of the symbol foo will no longer
228 be possible.
229
230
231
232 Using a dumped shared object with applied relocations as an applica‐
233 tions dependency normally requires that the application have the same
234 dependencies as the application that produced the dumped image. Dumping
235 shared objects, and the various flags associated with relocation pro‐
236 cessing, have some specialized uses. However, the technique is intended
237 as a building block for future technology.
238
239
240
241 The following code fragment, which is part of the dynamic executable
242 a.out, can be used to create a new version of the dynamic executable:
243
244
245 static char * dumped = 0;
246 const char * opath = "./a.out.new";
247 ...
248 if (dumped == 0) {
249 char buffer[100];
250 int size;
251 time_t seconds;
252 ...
253 /* Perform data initialization */
254 seconds = time((time_t *)0);
255 size = cftime(buffer, (char *)0, &seconds);
256 if ((dumped = (char *)malloc(size + 1)) == 0) {
257 (void) printf("malloc failed: %s\n", strerror(errno));
258 return (1);
259 }
260 (void) strcpy(dumped, buffer);
261 ...
262 /*
263 * Tear down any undesirable data initializations and
264 * dump the dynamic executables memory image.
265 */
266 _exithandle();
267 _exit(dldump(0, opath, RTLD_MEMORY));
268 }
269 (void) printf("Dumped: %s\n", dumped);
270
271
272
273 Any modifications made to the dynamic executable, up to the point the
274 dldump() call is made, are saved in the new object a.out.new. This
275 mechanism allows the executable to update parts of its data segment and
276 heap prior to creating the new object. In this case, the date the exe‐
277 cutable is dumped is saved in the new object. The new object can then
278 be executed without having to carry out the same (presumably expensive)
279 initialization.
280
281
282
283 For greatest flexibility, this example does not save any relocated
284 information. The elements of the dynamic executable ipath that have
285 been modified by relocations at process startup, that is, references to
286 external functions, are returned to the values of these elements as
287 they existed in the ipath disc file. This preservation of relocation
288 records allows the new dynamic executable to be flexible, and correctly
289 bind and initialize to its dependencies when executed on the same or
290 newer upgrades of the OS.
291
292
293
294 Fixing relocations by applying some of the relocation flags would bind
295 the new object to the dependencies presently mapped as part of the
296 process calling dldump(). It may also remove necessary copy relocation
297 processing required for the correct initialization of its shared object
298 dependencies. Therefore, if the new dynamic executables' dependencies
299 have no specialized initialization requirements, the executable may
300 still only interact correctly with the dependencies to which it binds
301 if they were mapped to the same locations as they were when dldump()
302 was called.
303
304
305
306 Note that for dynamic executables, RTLD_REL_RELATIVE, RTLD_REL_EXEC,
307 and RTLD_REL_SELF have no effect, as relocations within the dynamic
308 executable will have been fixed when it was created by ld(1).
309
310
311
312 When RTLD_MEMORY is used, care should be taken to insure that dumped
313 data sections that reference external objects are not reused without
314 appropriate re-initialization. For example, if a data item contains a
315 file descriptor, a variable returned from a shared object, or some
316 other external data, and this data item has been initialized prior to
317 the dldump() call, its value will have no meaning in the new dumped
318 image.
319
320
321
322 When RTLD_MEMORY is used, any modification to a data item that is ini‐
323 tialized via a relocation whose relocation record will be retained in
324 the new image will effectively be lost or invalidated within the new
325 image. For example, if a pointer to an external object is incremented
326 prior to the dldump() call, this data item will be reset to its disc
327 file contents so that it can be relocated when the new image is used;
328 hence, the previous increment is lost.
329
330
331
332 Non-idempotent data initializations may prevent the use of RTLD_MEMORY.
333 For example, the addition of elements to a linked-list via init sec‐
334 tions can result in the linked-list data being captured in the new
335 image. Running this new image may result in init sections continuing to
336 add new elements to the list without the prerequisite initialization of
337 the list head. It is recommended that _exithandle(3C) be called before
338 dldump() to tear down any data initializations established via initial‐
339 ization code. Note that this may invalidate the calling image; thus,
340 following the call to dldump(), only a call to _Exit(2) should be made.
341
342
344 The dldump() function is one of a family of functions that give the
345 user direct access to the dynamic linking facilities. These facilities
346 are available to dynamically-linked processes only. See Linker and
347 Libraries Guide).
348
350 See attributes(5) for descriptions of the following attributes:
351
352
353
354
355 ┌─────────────────────────────┬─────────────────────────────┐
356 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
357 ├─────────────────────────────┼─────────────────────────────┤
358 │Availability │SUNWcsu │
359 ├─────────────────────────────┼─────────────────────────────┤
360 │MT-Level │MT-Safe │
361 └─────────────────────────────┴─────────────────────────────┘
362
364 ld(1), ld.so.1(1), strip(1), _Exit(2), brk(2), exec(2),
365 _exithandle(3C), dladdr(3C), dlclose(3C), dlerror(3C), dlopen(3C),
366 dlsym(3C), end(3C), malloc(3C), attributes(5)
367
368
369 Linker and Libraries Guide
370
372 These functions are available to dynamically-linked processes only.
373
374
375 Any NOBITS sections within the ipath are expanded to PROGBITS sections
376 within the opath. NOBITS sections occupy no space within an ELF file
377 image. NOBITS sections declare memory that must be created and zero-
378 filled when the object is mapped into the runtime environment. .bss is
379 a typical example of this section type. PROGBITS sections, on the other
380 hand, hold information defined by the object within the ELF file image.
381 This section conversion reduces the runtime initialization cost of the
382 new dumped object but increases the objects' disc space requirement.
383
384
385 When a shared object is dumped, and relocations are applied which are
386 knowledgeable of the base address of the mapped object, the new object
387 is fixed to this new base address. The dumped object has its ELF type
388 reclassified to be a dynamic executable. The dumped object can be pro‐
389 cessed by the runtime linker, but is not valid as input to the link-
390 editor.
391
392
393 If relocations are applied to the new object, any remaining relocation
394 records are reorganized for better locality of reference. The reloca‐
395 tion sections are renamed to .SUNW_reloc and the association with the
396 section to relocate, is lost. Only the offset of the relocation record
397 is meaningful. .SUNW_reloc relocations do not make the new object
398 invalid to either the runtime linker or link-editor, but can reduce the
399 objects analysis with some ELF readers.
400
401
402
403SunOS 5.11 1 Mar 2004 dldump(3C)