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