1.\" 2.\" Copyright (c) 2003 Alexey Zelkin <phantom@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd February 14, 2003 29.Os 30.Dt DLINFO 3 31.Sh NAME 32.Nm dlinfo 33.Nd information about dynamically loaded object 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In link.h 38.In dlfcn.h 39.Ft int 40.Fn dlinfo "void * restrict handle" "int request" "void * restrict p" 41.Sh DESCRIPTION 42The 43.Fn dlinfo 44function provides information about dynamically loaded object. 45The action taken by 46.Fn dlinfo 47and exact meaning and type of 48.Fa p 49argument depend on value of the 50.Fa request 51argument provided by caller. 52.Pp 53The 54.Fa handle 55argument is either the value returned from the 56.Xr dlopen 3 57function call or special handle 58.Dv RTLD_SELF . 59If 60.Fa handle 61is the value returned from 62.Xr dlopen 3 , 63the information returned by the 64.Fn dlinfo 65function pertains to the specified object. 66If handle is the special handle 67.Dv RTLD_SELF , 68the information returned pertains to the caller itself. 69.Pp 70Possible values for the 71.Fa request 72argument are: 73.Bl -tag -width indent 74.It Dv RTLD_DI_LINKMAP 75Retrieve the 76.Vt Link_map 77.Pq Vt "struct link_map" 78structure pointer for the specified 79.Fa handle . 80On successful return, the 81.Fa p 82argument is filled with the pointer to the 83.Vt Link_map 84structure 85.Pq Fa "Link_map **p" 86describing a shared object specified by the 87.Fa handle 88argument. 89The 90.Vt Link_map 91structures are maintained as a doubly linked list by 92.Xr ld.so 1 , 93in the same order as 94.Xr dlopen 3 95and 96.Xr dlclose 3 97are called. 98See 99.Sx EXAMPLES , 100example 1. 101.Pp 102The 103.Vt Link_map 104structure is defined in 105.In link.h 106and has the following members: 107.Bd -literal -offset indent 108caddr_t l_addr; /* Base Address of library */ 109const char *l_name; /* Absolute Path to Library */ 110const void *l_ld; /* Pointer to .dynamic in memory */ 111struct link_map *l_next, /* linked list of mapped libs */ 112 *l_prev; 113.Ed 114.Bl -tag -width ".Va l_addr" 115.It Va l_addr 116The base address of the object loaded into memory. 117.It Va l_name 118The full name of the loaded shared object. 119.It Va l_ld 120The address of the dynamic linking information segment 121.Pq Dv PT_DYNAMIC 122loaded into memory. 123.It Va l_next 124The next 125.Vt Link_map 126structure on the link-map list. 127.It Va l_prev 128The previous 129.Vt Link_map 130structure on the link-map list. 131.El 132.It Dv RTLD_DI_SERINFO 133Retrieve the library search paths associated with the given 134.Fa handle 135argument. 136The 137.Fa p 138argument should point to 139.Vt Dl_serinfo 140structure buffer 141.Pq Fa "Dl_serinfo *p" . 142The 143.Vt Dl_serinfo 144structure must be initialized first with the 145.Dv RTLD_DI_SERINFOSIZE 146request. 147.Pp 148The returned 149.Vt Dl_serinfo 150structure contains 151.Va dls_cnt 152.Vt Dl_serpath 153entries. 154Each entry's 155.Va dlp_name 156field points to the search path. 157The corresponding 158.Va dlp_info 159field contains one of more flags indicating the origin of the path (see the 160.Dv LA_SER_* 161flags defined in the 162.In link.h 163header file). 164See 165.Sx EXAMPLES , 166example 2, for a usage example. 167.It Dv RTLD_DI_SERINFOSIZE 168Initialize a 169.Vt Dl_serinfo 170structure for use in a 171.Dv RTLD_DI_SERINFO 172request. 173Both the 174.Va dls_cnt 175and 176.Va dls_size 177fields are returned to indicate the number of search paths applicable 178to the handle, and the total size of a 179.Vt Dl_serinfo 180buffer required to hold 181.Va dls_cnt 182.Vt Dl_serpath 183entries and the associated search path strings. 184See 185.Sx EXAMPLES , 186example 2, for a usage example. 187.It Va RTLD_DI_ORIGIN 188Retrieve the origin of the dynamic object associated with the handle. 189On successful return, 190.Fa p 191argument is filled with the 192.Vt char 193pointer 194.Pq Fa "char *p" . 195.El 196.Sh RETURN VALUES 197The 198.Fn dlinfo 199function returns 0 on success, or \-1 if an error occurred. 200Whenever an error has been detected, a message detailing it can 201be retrieved via a call to 202.Xr dlerror 3 . 203.Sh EXAMPLES 204Example 1: Using 205.Fn dlinfo 206to retrieve 207.Vt Link_map 208structure. 209.Pp 210The following example shows how dynamic library can detect the list 211of shared libraries loaded after caller's one. 212For simplicity, error checking has been omitted. 213.Bd -literal -offset indent 214Link_map *map; 215 216dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map); 217 218while (map != NULL) { 219 printf("%p: %s\\n", map->l_addr, map->l_name); 220 map = map->l_next; 221} 222.Ed 223.Pp 224Example 2: Using 225.Fn dlinfo 226to retrieve the library search paths. 227.Pp 228The following example shows how a dynamic object can inspect the library 229search paths that would be used to locate a simple filename with 230.Xr dlopen 3 . 231For simplicity, error checking has been omitted. 232.Bd -literal -offset indent 233Dl_serinfo _info, *info = &_info; 234Dl_serpath *path; 235unsigned int cnt; 236 237/* determine search path count and required buffer size */ 238dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info); 239 240/* allocate new buffer and initialize */ 241info = malloc(_info.dls_size); 242info->dls_size = _info.dls_size; 243info->dls_cnt = _info.dls_cnt; 244 245/* obtain sarch path information */ 246dlinfo(RTLD_SELF, RTLD_DI_SERINFO, (void *)info); 247 248path = &info->dls_serpath[0]; 249 250for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) { 251 (void) printf("%2d: %s\\n", cnt, path->dls_name); 252} 253.Ed 254.Sh SEE ALSO 255.Xr rtld 1 , 256.Xr dladdr 3 , 257.Xr dlopen 3 , 258.Xr dlsym 3 259.Sh HISTORY 260The 261.Fn dlinfo 262function first appeared in the Solaris operating system. 263In 264.Fx , 265it first appeared in 266.Fx 4.8 . 267.Sh AUTHORS 268.An -nosplit 269The 270.Fx 271implementation of the 272.Fn dlinfo 273function was originally written by 274.An Alexey Zelkin 275.Aq phantom@FreeBSD.org 276and later extended and improved by 277.An Alexander Kabaev 278.Aq kan@FreeBSD.org . 279.Pp 280The manual page for this function was written by 281.An Alexey Zelkin 282.Aq phantom@FreeBSD.org . 283