1dldump(3C)               Standard C Library Functions               dldump(3C)
2
3
4

NAME

6       dldump - create a new file from a dynamic object component of the call‐
7       ing process
8

SYNOPSIS

10       #include <dlfcn.h>
11
12       int dldump(const char * ipath, const char * opath, int flags);
13
14

DESCRIPTION

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

RETURN VALUES

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

EXAMPLES

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

USAGE

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

ATTRIBUTES

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

SEE ALSO

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

NOTES

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)
Impressum