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.13 2008/05/02 02:05:03 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 Dv 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 88structures are maintained as double-linked list by 89.Xr rtld 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 102.In link.h 103and has the following members: 104.Bd -literal 105 caddr_t l_addr; /* Base Address of library */ 106 const char *l_name; /* Absolute Path to Library */ 107 const void *l_ld; /* Pointer to .dynamic in memory */ 108 struct link_map *l_next, /* linked list of of mapped libs */ 109 *l_prev; 110.Ed 111.Bl -tag -width Ds 112.It l_addr 113The base address of the object loaded into memory. 114.It l_name 115The full name of loaded shared object. 116.It l_ld 117The address of dynamic linking information segment 118.Dv ( PT_DYNAMIC ) 119loaded into memory. 120.It l_next 121The next Link_map structure on the link-map list. 122.It l_prev 123The previous Link_map structure on the link-map list. 124.El 125.It Dv RTLD_DI_SERINFO 126Retrieve the library search paths associated with given 127.Fa handle 128argument. 129The 130.Fa p 131argument should point to 132.Ft Dl_serinfo 133structure buffer 134.Fa ( Dl_serinfo *p ) . 135.Ft Dl_serinfo 136structure must be initialized first with a 137.Dv RTLD_DI_SERINFOSIZE 138request. 139.Pp 140The returned 141.Ft Dl_serinfo 142structure contains 143.Fa dls_cnt 144.Ft Dl_serpath 145entries. 146Each entry's 147.Fa dlp_name 148field points to the search path. 149The corresponding 150.Fa dlp_info 151field contains one of more flags indicating the origin of the path (see the 152.Dv LA_SER_* 153flags defined in the 154.In link.h 155header file.) 156See 157.Sx EXAMPLES 158(Example 2) for usage example. 159.It Dv RTLD_DI_SERINFOSIZE 160Initialize a 161.Ft Dl_serinfo 162structure for use in a 163.Dv RTLD_DI_SERINFO 164request. 165Both the 166.Fa dls_cnt 167and 168.Fa dls_size 169fields are returned to indicate the number of search paths applicable 170to the handle, and the total size of a 171.Ft Dl_serinfo 172buffer required to hold 173.Fa dls_cnt 174.Ft Dl_serpath 175entries and the associated search path strings. 176See 177.Sx EXAMPLES 178(Example 2) for usage example. 179.It Dv RTLD_DI_ORIGIN 180Retrieve the origin of the dynamic object associated with the handle. 181On successful return 182.Fa p 183argument is filled with 184.Ft char 185pointer 186.Ft ( char *p ) . 187.El 188.Sh RETURN VALUES 189.Fn dlinfo 190returns 0 on success, or -1 if error occurred. 191Whenever an error has been detected, a message detailing it can 192be retrieved via a call to 193.Fn dlerror . 194.Sh EXAMPLES 195Example 1: Using 196.Fn dlinfo 197to retrieve Link_map structure. 198.Pp 199The following example shows how dynamic library can detect the list 200of shared libraries loaded after caller's one. 201For simplicity, error checking has been omitted. 202.Bd -literal 203 Link_map *map; 204 205 dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map); 206 207 while (map != NULL) { 208 printf("%p: %s\en", map->l_addr, map->l_name); 209 map = map->l_next; 210 } 211.Ed 212.Pp 213Example 2: Using 214.Fn dlinfo 215to retrieve the library search paths. 216.Pp 217The following example shows how a dynamic object can inspect the library 218search paths that would be used to locate a simple filename with 219.Fn dlopen . 220For simplicity, error checking has been omitted. 221.Bd -literal 222 Dl_serinfo _info, *info = &_info; 223 Dl_serpath *path; 224 unsigned int cnt; 225 226 /* determine search path count and required buffer size */ 227 dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info); 228 229 /* allocate new buffer and initialize */ 230 info = malloc(_info.dls_size); 231 info->dls_size = _info.dls_size; 232 info->dls_cnt = _info.dls_cnt; 233 234 /* obtain sarch path information */ 235 dlinfo(RTLD_SELF, RTLD_DI_SERINFO, (void *)info); 236 237 path = &info->dls_serpath[0]; 238 239 for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) { 240 (void) printf("%2d: %s\en", cnt, path->dls_name); 241 } 242.Ed 243.Sh SEE ALSO 244.Xr rtld 1 , 245.Xr dladdr 3 , 246.Xr dlopen 3 , 247.Xr dlsym 3 248.Sh HISTORY 249The 250.Fn dlinfo 251function first appeared in the Solaris operating system. 252In 253.Fx 254it first appeared in 255.Fx 4.8 . 256.Sh AUTHORS 257.An -nosplit 258The 259.Fx 260implementation of 261.Fn dlinfo 262function was originally written by 263.An Alexey Zelkin 264.Aq phantom@FreeBSD.org 265and later extended and improved by 266.An Alexander Kabaev 267.Aq kan@FreeBSD.org . 268.Pp 269The manual page for this function was written by 270.An Alexey Zelkin 271.Aq phantom@FreeBSD.org . 272