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