Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DLINFO(3)		 BSD Library Functions Manual		     DLINFO(3)

     dlinfo -- information about dynamically loaded object

     Standard C	Library	(libc, -lc)

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

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

     The dlinfo() function provides information	about dynamically loaded ob-
     ject.  The	action taken by	dlinfo() and exact meaning and type of p argu-
     ment 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:

	     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) de-
	     scribing a	shared object specified	by the handle argument.	 The
	     Link_map structures are maintained	as a doubly linked list	by, 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_base;    /* 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 */
		   caddr_t	   l_addr;     /* Load Offset of library */
		   const char	   *l_refname; /* Object this one filters for */

	     l_base  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.

	     l_addr  The load offset of	the object, that is, the difference
		     between the actual	load address and the base virtual ad-
		     dress the object was linked at.

		     A name of the object this object filters for, if any.  If
		     there are more then one filtee, a name from the first
		     DT_FILTER dynamic entry is	supplied.

	     Retrieve the library search paths associated with the given
	     handle argument.  The p argument should point to Dl_serinfo
	     structure buffer (Dl_serinfo *p).	The Dl_serinfo structure must
	     be	initialized first with the RTLD_DI_SERINFOSIZE request.

	     The returned Dl_serinfo structure contains	dls_cnt	Dl_serpath en-
	     tries.  Each entry's dlp_name field points	to the search path.
	     The corresponding dlp_info	field contains one of more flags indi-
	     cating the	origin of the path (see	the LA_SER_* flags defined in
	     the <link.h> header file).	 See EXAMPLES, example 2, for a	usage

	     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.

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

     The dlinfo() function returns 0 on	success, or -1 if an error occurred.
     Whenever an error has been	detected, a message detailing it can be	re-
     trieved via a call	to dlerror(3).

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

     rtld(1), dladdr(3), dlopen(3), dlsym(3)

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

     The FreeBSD implementation	of the dlinfo()	function was originally	writ-
     ten by Alexey Zelkin <>	and later extended and im-
     proved by Alexander Kabaev	<>.

     The manual	page for this function was written by Alexey Zelkin

BSD				 May 21, 2020				   BSD


Want to link to this manual page? Use this URL:

home | help