dldump man page on SunOS

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
SunOS logo
[printable version]

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' disc
       file. Relocations 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 can be	obtained  from
       the objects' memory image as this data exists in the calling process.

       These  techniques  allow	 the  new  object  to be executed with a lower
       startup cost. This reduction can be because of less  relocations	 being
       required to load the object, or because of a reduction in the data pro‐
       cessing requirements of the object. However, limitations can  exist  in
       using  these  techniques.  The  application  of	relocations to the new
       dynamic object opath can restrict its flexibility within a  dynamically
       changing environment. In addition, limitations in regards to data usage
       can 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, one of the process's dependen‐
       cies,   or  an  object  that  has  been	preloaded.  See	 exec(2),  and
       ld.so.1(1).

       As part of the runtime  processing  of  a  dynamic  object,  relocation
       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 associ‐
       ated symbol, and results in  a  binding	to  the	 dynamic  object  that
       defines	this  symbol.  The symbol definition can originate from 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 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  can	be  or'ed  into the flags parameter to
       affect the relocations that are 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.

       Note that for dynamic  executables,  RTLD_REL_RELATIVE,	RTLD_REL_EXEC,
       and RTLD_REL_SELF have no effect. See EXAMPLES.

       If relocations, knowledgeable of the base address of the mapped object,
       are applied to the new object opath, then the new object becomes	 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 relocation will not be applied
       more than once. Otherwise, the new object opath will retain the reloca‐
       tion 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 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 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.
	   RTLD_STRIP  reduces the size of the opath disc 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 disc	 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 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  relocation
       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 relocations 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 flexibil‐
       ity 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.

       For example, the use of RTLD_REL_SELF will cause any references to sym‐
       bols  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. Therefore, opath will have one less binding that must  be  com‐
       puted 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 applica‐
       tions dependency normally requires that the application have  the  same
       dependencies  as the application that produced the dumped image.	 Dump‐
       ing 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 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.

       For  greatest  flexibility,  this  example  does not save any relocated
       information. The elements of the dynamic	 executable  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 executed 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 relocations 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  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  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 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  Linker  and
       Libraries Guide).

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      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(3C),  dlclose(3C),  dlerror(3C),   dlopen(3C),
       dlsym(3C), 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 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' disc space requirement.

       When a shared object is dumped, and relocations are applied  which  are
       knowledgeable  of the base address of the mapped object, the new object
       is fixed to this new base address. The dumped object has its  ELF  type
       reclassified  to be a dynamic executable. The dumped object can be pro‐
       cessed 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 are reorganized for better locality of reference.  The  reloca‐
       tion  sections  are renamed to .SUNW_reloc and the association with the
       section to relocate, is lost. Only the offset of the relocation	record
       is  meaningful.	.SUNW_reloc  relocations  do  not  make the new object
       invalid to either the runtime linker or link-editor, but can reduce the
       objects analysis with some ELF readers.

SunOS 5.10			  1 Mar 2004			    dldump(3C)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net