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