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