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