dlinfo man page on SmartOS

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

DLINFO(3C)							    DLINFO(3C)

NAME
       dlinfo - dynamic load information

SYNOPSIS
       #include <dlfcn.h>
       #include <link.h>
       #include <limits.h>
       #include <sys/mman.h>

       int dlinfo(void *handle, int request, void *p);

DESCRIPTION
       The  dlinfo()  function	sets  or extracts information from the runtime
       linker ld.so.1(1). This function is loosely modeled after the  ioctl(2)
       function. The request argument and a third argument of varying type are
       passed to dlinfo(). The action taken by dlinfo() depends on  the	 value
       of the request that is provided.

       The  handle  argument  is  either  the  value  that  is returned from a
       dlopen(3C) or dlmopen() call, or the special handle RTLD_SELF. A handle
       argument	 is  required  for  all	 requests  except  RTLD_DI_CONFIGADDR,
       RTLD_DI_GETSIGNAL, and RTLD_DI_SETSIGNAL.  If handle is the value  that
       is returned from a dlopen() or dlmopen() call, the information returned
       by the dlinfo() call pertains to the specified object. If handle is the
       special handle RTLD_SELF, the information returned by the dlinfo() call
       pertains to the caller.

       The request argument can take the following values:

       RTLD_DI_ARGSINFO

	   Obtain process argument information. The p argument	is  a  pointer
	   (Dl_argsinfo_t  *p). The following elements from this structure are
	   initialized:

	   dla_argc
		       The number of arguments passed to the process.

	   dla_argv
		       The argument array passed to the process.

	   dla_envp
		       The active environment variable array that is available
		       to  the	process.  This element initially points to the
		       environment variable array that is  made	 available  to
		       exec(2). This element can be updated should an alterna‐
		       tive environment be established	by  the	 process.  See
		       putenv(3C).

	   dla_auxv
		       The auxiliary vector array passed to the process.

	   A  process  can  be	established  from executing the runtime linker
	   directly from the command line. See ld.so.1(1).  The	 Dl_argsinfo_t
	   information	reflects the information that is made available to the
	   application regardless of how the runtime linker has been invoked.

       RTLD_DI_CONFIGADDR

	   Obtain the configuration file information.  The  p  argument	 is  a
	   Dl_info_t  pointer (Dl_info_t *p). The following elements from this
	   structure are initialized:

	   dli_fname
			The full name of the configuration file.

	   dli_fbase
			The base address of the configuration file loaded into
			memory.

       RTLD_DI_LINKMAP

	   Obtain  the	Link_map for the handle that is specified. The p argu‐
	   ment points to a Link_map pointer (Link_map **p). The actual	 stor‐
	   age for the Link_map structure is maintained by ld.so.1.

	   The Link_map structure includes the following members:

		 unsigned long l_addr;	    /* base address */
		 char	       *l_name;	    /* object name */
		 Elf32_Dyn     *l_ld;	    /* .dynamic section */
		 Link_map      *l_next;	    /* next link object */
		 Link_map      *l_prev;	    /* previous link object */
		 char	       *l_refname;  /* filter reference name */

	   l_addr
			The base address of the object loaded into memory.

	   l_name
			The  full name of the loaded object. This full name is
			the filename of the object as referenced by ld.so.1.

	   l_ld
			Points to the SHT_DYNAMIC structure.

	   l_next
			The next Link_map on the link-map list. Other  objects
			on the same link-map list as the current object can be
			examined by following the l_next and l_prev members.

	   l_prev
			The previous Link_map on the link-map list.

	   l_refname
			If the object that is referenced  is  a	 filter,  this
			member	points	to  the	 name of the object being fil‐
			tered. If the object is not a filter, this  member  is
			0. See the Linker and Libraries Guide.

       RTLD_DI_LMID

	   Obtain  the	ID  for	 the  link-map	list  upon which the handle is
	   loaded. The p argument is a Lmid_t pointer (Lmid_t *p).

       RTLD_DI_MMAPCNT

	   Determine the number of segment mappings for	 the  handle  that  is
	   specified,  for use in a RTLD_DI_MMAPS request. The p argument is a
	   uint_t pointer  (uint_t  *p).  On  return  from  a  RTLD_DI_MMAPCNT
	   request, the uint_t value that is pointed to by p contains the num‐
	   ber of segment mappings that the associated object uses.

	   To obtain  the  complete  mapping  information  for	an  object,  a
	   mmapobj_result_t  array  for	 RTLD_DI_MMAPCNT  entries must be pro‐
	   vided. This array is assigned to the dlm_maps member, and the  num‐
	   ber	of  entries available in the arry are assigned to the dlm_acnt
	   member.   This  initialized	structure  is	then   passed	to   a
	   RTLD_DI_MMAPS request. See EXAMPLES.

       RTLD_DI_MMAPS

	   Obtain  segment  mapping  information for the handle that is speci‐
	   fied. The p argument is a Dl_mapinfo_t pointer  (Dl_mapinfo_t  *p).
	   This	 structure  can be initialized from the mapping count obtained
	   from a previous RTLD_DI_MMAPCNT request.

	   Segment  mapping  information  is   provided	  in   an   array   of
	   mmapobj_result_t  structures	 that originate from the mmapobj(2) of
	   the associated object.  The dlm_acnt member, typically  initialized
	   from	 a  previous  RTLD_DI_MMAPCNT request, indicates the number of
	   enteries in a mmapobj_result_t array. This array is assigned to the
	   dlm_maps  member.  This  initialized	 structure is then passed to a
	   RTLD_DI_MMAPS request, where the  segment  mapping  information  is
	   copied to the mmapobj_result_t array. The dlm_rcnt member indicates
	   the number of mmapobj_result_t element entries that	are  returned.
	   See EXAMPLES.

       RTLD_DI_SERINFO

	   Obtain  the	library search paths for the handle that is specified.
	   The p argument is a Dl_serinfo_t pointer (Dl_serinfo_t *p).	A user
	   must	  first	  initialize   the   Dl_serinfo_t   structure  with  a
	   RTLD_DI_SERINFOSIZE request. See EXAMPLES.

	   The returned Dl_serinfo_t structure contains	 dls_cnt  Dl_serpath_t
	   entries.  Each  entry's  dlp_name member points to the search path.
	   The corresponding dlp_info member contains one of more flags	 indi‐
	   cating  the	origin	of  the	 path. See the LA_SER_* flags that are
	   defined in <link.h>.

       RTLD_DI_SERINFOSIZE

	   Initialize a Dl_serinfo_t structure for the handle that  is	speci‐
	   fied,  for  use  in a RTLD_DI_SERINFO request. Both the dls_cnt and
	   dls_size members are returned. The  dls_cnt	member	indicates  the
	   number  of  search  paths  that  are	 applicable to the handle. The
	   dls_size member indicates the total size of a  Dl_serinfo_t	buffer
	   required  to	 hold  dls_cnt Dl_serpath_t entries and the associated
	   search path strings. The  p	argument  is  a	 Dl_serinfo_t  pointer
	   (Dl_serinfo_t *p).

	   To  obtain the complete path information, a new Dl_serinfo_t buffer
	   of size dls_size should be allocated. This  new  buffer  should  be
	   initialized	with the dls_cnt and dls_size entries. The initialized
	   buffer is then passed to a RTLD_DI_SERINFO request. See EXAMPLES.

       RTLD_DI_ORIGIN

	   Obtain the origin of the dynamic object that is associated with the
	   handle. The p argument is a char pointer (char *p). The dirname(3C)
	   of the associated object's realpath(3C), which  can	be  no	larger
	   than {PATH_MAX}, is copied to the pointer p.

       RTLD_DI_GETSIGNAL

	   Obtain the numeric signal number used by the runtime linker to kill
	   the process in the event of a fatal runtime error. The  p  argument
	   is  an  int	pointer	 (int  *p). The signal number is copied to the
	   pointer p.

	   By default, the signal used by the runtime linker  to  terminate  a
	   process  is	SIGKILL. See thr_kill(3C). This default can be changed
	   by calling dlinfo() with RTLD_DI_SETSIGNAL or by setting the	 envi‐
	   ronment variable LD_SIGNAL. See ld.so.1(1).

       RTLD_DI_SETSIGNAL

	   Provide  a numeric signal number used by the runtime linker to kill
	   the process in the event of a fatal runtime error. The  p  argument
	   is  an  int	pointer	 (int *p). The value pointed to by p is estab‐
	   lished as the terminating signal value.

	   The current signal number used by the runtime linker to terminate a
	   process  can be obtained from dlinfo() using RTLD_DI_GETSIGNAL. Use
	   of the RTLD_DI_SETSIGNAL option is equivalent to setting the	 envi‐
	   ronment variable LD_SIGNAL. See ld.so.1(1).

RETURN VALUES
       The dlinfo() function returns −1 if the request is invalid, the parame‐
       ter p is NULL, or the Dl_serinfo_t structure  is	 uninitialized	for  a
       RTLD_DI_SERINFO	request.  dlinfo() also returns −1 if the handle argu‐
       ment does not refer to a valid object opened by dlopen(), or is not the
       special	handle RTLD_SELF. Detailed diagnostic information is available
       with dlerror(3C).

EXAMPLES
       Example 1 Use dlinfo() to obtain library search paths.

       The following example demonstrates how a dynamic object can inspect the
       library	search	paths  that  would be used to locate a simple filename
       with dlopen(). For simplicity, error checking has been omitted.

	     Dl_serinfo_t   _info, *info = &_info;
	     Dl_serpath_t   *path;
	     uint_t	    cnt;

	     /* determine search path count and required buffer size */
	     dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, info);

	     /* allocate new buffer and initialize */
	     info = malloc(_info.dls_size);
	     info->dls_size = _info.dls_size;
	     info->dls_cnt = _info.dls_cnt;

	     /* obtain sarch path information */
	     dlinfo(RTLD_SELF, RTLD_DI_SERINFO, info);

	     path = &info->dls_serpath[0];

	     for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) {
		 (void) printf("%2d: %s\n", cnt, path->dls_name);
	     }

       Example 2 Use dlinfo() to obtain segment information.

       The following example demonstrates how a dynamic object can inspect its
       segment	mapping	 information.  For simplicity, error checking has been
       omitted

	     Dl_mapinfo_t   mi;
	     uint_t	    cnt;

	     /* determine the number of segment mappings */
	     dlinfo(RTLD_SELF, RTLD_DI_MMAPCNT, &mi.dlm_acnt);

	     /* allocate the appropriate mapping array */
	     mi.dlm_maps = malloc(mi.dlm_acnt * sizeof (mmapobj_result_t));

	     /* obtain the mapping information */
	     dlinfo(RTLD_SELF, RTLD_DI_MMAPS, &mi);

	     for (cnt = 0; cnt < mi.dlm_rcnt; cnt++) {
		 (void) printf("addr=%x - memory size=%x\n",
		     mi.dlm_maps[cnt].mr_addr, mi.dlm_maps[cnt].mr_msize);
	     }

USAGE
       The dlinfo() 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 Linker  and
       Libraries Guide.

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

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Stable	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ MT-Safe	      │
       └────────────────────┴─────────────────┘

SEE ALSO
       ld(1),	ld.so.1(1),   exec(2),	 ioctl(2),   mmapobj(2),  dirname(3C),
       dlclose(3C),   dldump(3C),    dlerror(3C),    dlopen(3C),    dlsym(3C),
       putenv(3C), realpath(3C), thr_kill(3C), attributes(5).

       Linker and Libraries Guide

				  Feb 4, 2009			    DLINFO(3C)
[top]

List of man pages available for SmartOS

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