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: src/lib/libc/gen/dlinfo.3,v 1.3.2.1 2003/02/20 20:42:45 kan Exp $ 27.\" $DragonFly: src/lib/libc/gen/dlinfo.3,v 1.5 2006/02/17 19:35:06 swildner Exp $ 28.\" 29.Dd February 14, 2003 30.Os 31.Dt DLINFO 3 32.Sh NAME 33.Nm dlinfo 34.Nd information about dynamically loaded object 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In link.h 39.In dlfcn.h 40.Ft int 41.Fn dlinfo "void * __restrict handle" "int request" "void * __restrict p" 42.Sh DESCRIPTION 43The 44.Fn dlinfo 45function provides information about dynamically loaded object. 46The action taken by 47.Fn dlinfo 48and exact meaning and type of 49.Fa p 50argument depend on value of the 51.Fa request 52argument provided by caller. 53.Pp 54A 55.Fa handle 56argument is either the value returned from a 57.Fn dlopen 58function call or special handle 59.Dv RTLD_SELF . 60If handle is the value returned from 61.Fn dlopen 62call, the information returned by the 63.Fn dlinfo 64function is pertains the specified object. 65If handle is the special handle 66.Dv RTLD_SELF , 67the information returned pertains to the caller itself. 68.Pp 69The following are possible values for 70.Fa request 71argument to be passed into 72.Fn dlinfo : 73.Bl -tag -width Ds 74.It RTLD_DI_LINKMAP 75Retrieve the Link_map (or 76.Ft struct link_map ) 77structure pointer for 78.Fa handle 79specified. 80On successful return the 81.Fa p 82argument is filled with pointer to Link_map structure 83.Ft ( Link_map **p ) 84describing shared object specified by 85.Fa handle 86argument. 87.Ft Link_map 88stuctures are maintained as double-linked list by 89.Xr ld.so 1 90in same order as 91.Fn dlopen 92and 93.Fn dlclose 94are called. 95See 96.Sx EXAMPLES 97(Example 1.) 98.Pp 99The 100.Ft Link_map 101structure is defined in <link.h> and have following members: 102.Pp 103.Bd -literal 104 caddr_t l_addr; /* Base Address of library */ 105 const char *l_name; /* Absolute Path to Library */ 106 const void *l_ld; /* Pointer to .dynamic in memory */ 107 struct link_map *l_next, /* linked list of of mapped libs */ 108 *l_prev; 109.Ed 110.Bl -tag -width Ds 111.It l_addr 112The base address of the object loaded into memory. 113.It l_name 114The full name of loaded shared object. 115.It l_ld 116The address of dynamic linking information segment 117.Dv ( PT_DYNAMIC ) 118loaded into memory. 119.It l_next 120The next Link_map structure on the link-map list. 121.It l_prev 122The previous Link_map structure on the link-map list. 123.El 124.It RTLD_DI_SERINFO 125Retrieve the library search paths associated with given 126.Fa handle 127argument. 128The 129.Fa p 130argument should point to 131.Ft Dl_serinfo 132structure buffer 133.Fa ( Dl_serinfo *p ) . 134.Ft Dl_serinfo 135structure must be initialized first with a 136.Dv RTLD_DI_SERINFOSIZE 137request. 138.Pp 139The returned 140.Ft Dl_serinfo 141structure contains 142.Dv dls_cnt 143.Ft Dl_serpath 144entries. 145Each entry's 146.Dv dlp_name 147field points to the search path. 148The corresponding 149.Dv dlp_info 150field contains one of more flags indicating the origin of the path (see the 151.Dv LA_SER_* 152flags defined in <link.h> header file.) 153See 154.Sx EXAMPLES 155(Example 2) for usage example. 156.It RTLD_DI_SERINFOSIZE 157Initialize a 158.Ft Dl_serinfo 159structure for use in a 160.Dv RTLD_DI_SERINFO 161request. 162Both the 163.Dv dls_cnt 164and 165.Dv dls_size 166fields are returned to indicate the number of search paths applicable 167to the handle, and the total size of a 168.Ft Dl_serinfo 169buffer required to hold 170.Dv dls_cnt 171.Ft Dl_serpath 172entries and the associated search path strings. 173See 174.Sx EXAMPLES 175(Example 2) for usage example. 176.It RTLD_DI_ORIGIN 177Retrieve the origin of the dynamic object associated with the handle. 178On successful return 179.Fa p 180argument is filled with 181.Ft char 182pointer 183.Ft ( char *p ) . 184.El 185.Sh RETURN VALUES 186.Fn dlinfo 187returns 0 on success, or -1 if error occured. 188Whenever an error has been detected, a message detailing it can 189be retrieved via a call to 190.Fn dlerror . 191.Sh EXAMPLES 192Example 1: Using 193.Fn dlinfo 194to retrieve Link_map structure. 195.Pp 196The following example shows how dynamic library can detect the list 197of shared libraries loaded after caller's one. 198For simplicity, error checking has been omitted. 199.Bd -literal 200 Link_map *map; 201 202 dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map); 203 204 while (map != NULL) { 205 printf("%p: %s\en", map->l_addr, map->l_name); 206 map = map->l_next; 207 } 208.Ed 209.Pp 210Example 2: Using 211.Fn dlinfo 212to retrieve the library search paths. 213.Pp 214The following example shows how a dynamic object can inspect the library 215search paths that would be used to locate a simple filename with 216.Fn dlopen . 217For simplicity, error checking has been omitted. 218.Bd -literal 219 Dl_serinfo _info, *info = &_info; 220 Dl_serpath *path; 221 unsigned int cnt; 222 223 /* determine search path count and required buffer size */ 224 dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info); 225 226 /* allocate new buffer and initialize */ 227 info = malloc(_info.dls_size); 228 info->dls_size = _info.dls_size; 229 info->dls_cnt = _info.dls_cnt; 230 231 /* obtain sarch path information */ 232 dlinfo(RTLD_SELF, RTLD_DI_SERINFO, (void *)info); 233 234 path = &info->dls_serpath[0]; 235 236 for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) { 237 (void) printf("%2d: %s\en", cnt, path->dls_name); 238 } 239.Ed 240.Sh SEE ALSO 241.Xr rtld 1 , 242.Xr dladdr 3 , 243.Xr dlopen 3 , 244.Xr dlsym 3 245.Sh HISTORY 246The 247.Fn dlinfo 248function first appeared in the Solaris operating system. 249In 250.Fx 251it first appeared in 252.Fx 4.8 . 253.Sh AUTHORS 254The 255.Fx 256implementation of 257.Fn dlinfo 258function was originally written by 259.An Alexey Zelkin 260.Aq phantom@FreeBSD.org 261and later extended and improved by 262.An Alexander Kabaev 263.Aq kan@FreeBSD.org . 264.Pp 265The manual page for this function was written by 266.An Alexey Zelkin 267.Aq phantom@FreeBSD.org . 268