FreeBSD Man Pages

dlinfo(3)

NAME

     dlinfo -- information about dynamically loaded object

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

     #include <link.h>
     #include <dlfcn.h>

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

DESCRIPTION

     The dlinfo() function provides information about dynamically loaded
     object.  The action taken by dlinfo() and exact meaning and type of p
     argument depend on value of the request argument provided by caller.

     The handle argument is either the value returned from the dlopen(3) func-
     tion call or special handle RTLD_SELF.  If handle is the value returned
     from dlopen(3), the information returned by the dlinfo() function per-
     tains to the specified object.  If handle is the special handle
     RTLD_SELF, the information returned pertains to the caller itself.

     Possible values for the request argument are:

     RTLD_DI_LINKMAP
	     Retrieve the Link_map (struct link_map) structure pointer for the
	     specified handle.	On successful return, the p argument is filled
	     with the pointer to the Link_map structure (Link_map **p)
	     describing a shared object specified by the handle argument.  The
	     Link_map structures are maintained as a doubly linked list by
	     ld.so(1), in the same order as dlopen(3) and dlclose(3) are
	     called.  See EXAMPLES, example 1.

	     The Link_map structure is defined in <link.h> and has the follow-
	     ing members:

		   caddr_t	   l_addr;    /* Base Address of library */
		   const char	   *l_name;   /* Absolute Path to Library */
		   const void	   *l_ld;     /* Pointer to .dynamic in memory */
		   struct link_map *l_next,   /* linked list of mapped libs */
				   *l_prev;

	     l_addr  The base address of the object loaded into memory.

	     l_name  The full name of the loaded shared object.

	     l_ld    The address of the dynamic linking information segment
		     (PT_DYNAMIC) loaded into memory.

	     l_next  The next Link_map structure on the link-map list.

	     l_prev  The previous Link_map structure on the link-map list.

     RTLD_DI_SERINFO
	     Retrieve the library search paths associated with the given
	     the <link.h> header file).  See EXAMPLES, example 2, for a usage
	     example.

     RTLD_DI_SERINFOSIZE
	     Initialize a Dl_serinfo structure for use in a RTLD_DI_SERINFO
	     request.  Both the dls_cnt and dls_size fields are returned to
	     indicate the number of search paths applicable to the handle, and
	     the total size of a Dl_serinfo buffer required to hold dls_cnt
	     Dl_serpath entries and the associated search path strings.  See
	     EXAMPLES, example 2, for a usage example.

     RTLD_DI_ORIGIN
	     Retrieve the origin of the dynamic object associated with the
	     handle.  On successful return, p argument is filled with the char
	     pointer (char *p).

EXAMPLES

     Example 1: Using dlinfo() to retrieve Link_map structure.

     The following example shows how dynamic library can detect the list of
     shared libraries loaded after caller's one.  For simplicity, error check-
     ing has been omitted.

	   Link_map *map;

	   dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map);

	   while (map != NULL) {
		   printf("%p: %s\n", map->l_addr, map->l_name);
		   map = map->l_next;
	   }

     Example 2: Using dlinfo() to retrieve the library search paths.

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

	   Dl_serinfo	    _info, *info = &_info;
	   Dl_serpath	   *path;
	   unsigned int     cnt;

	   /* determine search path count and required buffer size */
	   dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)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, (void *)info);

	   path = &info->dls_serpath[0];

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

HISTORY

     The dlinfo() function first appeared in the Solaris operating system.  In
     FreeBSD, it first appeared in FreeBSD 4.8.

AUTHORS

     The FreeBSD implementation of the dlinfo() function was originally writ-
     ten by Alexey Zelkin <phantom@FreeBSD.org> and later extended and
     improved by Alexander Kabaev <kan@FreeBSD.org>.

     The manual page for this function was written by Alexey Zelkin
     <phantom@FreeBSD.org>.

FreeBSD 5.4		       February 14, 2003		   FreeBSD 5.4

SPONSORED LINKS