1.\" $NetBSD: dlinfo.3,v 1.7 2022/03/06 23:36:01 andvar Exp $ 2.\" 3.\" Copyright (c) 2003 Alexey Zelkin <phantom@FreeBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD: head/lib/libc/gen/dlinfo.3 267774 2014-06-23 08:25:03Z bapt $ 28.\" 29.Dd January 13, 2020 30.Dt DLINFO 3 31.Os 32.Sh NAME 33.Nm dlinfo 34.Nd information about a dynamically loaded object 35.Sh LIBRARY 36(These functions are not in a library. 37They are included in every 38dynamically linked program automatically.) 39.Sh SYNOPSIS 40.In link.h 41.In dlfcn.h 42.Ft int 43.Fn dlinfo "void *handle" "int request" "void *p" 44.Sh DESCRIPTION 45The 46.Fn dlinfo 47function provides information about a dynamically loaded object. 48The action taken by 49.Fn dlinfo 50and exact meaning and type of 51.Fa p 52argument depend on value of the 53.Fa request 54argument provided by caller. 55.Pp 56The 57.Fa handle 58argument is either the value returned from the 59.Xr dlopen 3 60function call or special handle 61.Dv RTLD_SELF . 62If 63.Fa handle 64is the value returned from 65.Xr dlopen 3 , 66the information returned by the 67.Fn dlinfo 68function pertains to the specified object. 69If 70.Fa handle 71is the special handle 72.Dv RTLD_SELF , 73the information returned pertains to the caller itself. 74.Pp 75Possible values for the 76.Fa request 77argument are: 78.Bl -tag -width "Dv RTLD_" 79.It Dv RTLD_DI_LINKMAP 80Retrieve the pointer to the 81.Vt Link_map 82for the specified 83.Fa handle . 84On successful return, the 85.Fa p 86argument is filled with the pointer to the 87.Vt Link_map 88structure 89.Pq Fa "Link_map **p" 90describing a shared object specified by the 91.Fa handle 92argument. 93The 94.Vt Link_map 95structures are maintained as a doubly linked list by 96.Xr ld.so 1 , 97in the same order as 98.Xr dlopen 3 99and 100.Xr dlclose 3 101are called. 102.Pp 103The 104.Vt Link_map 105structure is defined in 106.In link.h 107and has the following members: 108.Bd -literal -offset indent 109caddr_t l_addr; /* Base Address of library */ 110#ifdef __mips__ 111caddr_t l_offs; /* Load Offset of library */ 112#endif 113const char *l_name; /* Absolute Path to Library */ 114void *l_ld; /* Pointer to .dynamic in memory */ 115struct link_map *l_next, /* linked list of mapped libs */ 116 *l_prev; 117.Ed 118.Bl -tag -width Va 119.It Va l_addr 120The base address of the object loaded into memory. 121.It Va l_name 122The absolute pathname of the loaded shared object. 123.It Va l_ld 124The address of the dynamic linking information segment 125.Pq Dv PT_DYNAMIC 126loaded into memory. 127.It Va l_next 128The next 129.Vt Link_map 130structure on the link-map list. 131.It Va l_prev 132The previous 133.Vt Link_map 134structure on the link-map list. 135.El 136.\" .It Dv RTLD_DI_SERINFO 137.\" Retrieve the library search paths associated with the given 138.\" .Fa handle 139.\" argument. 140.\" The 141.\" .Fa p 142.\" argument should point to 143.\" .Vt Dl_serinfo 144.\" structure buffer 145.\" .Pq Fa "Dl_serinfo *p" . 146.\" The 147.\" .Vt Dl_serinfo 148.\" structure must be initialized first with the 149.\" .Dv RTLD_DI_SERINFOSIZE 150.\" request. 151.\" .Pp 152.\" The returned 153.\" .Vt Dl_serinfo 154.\" structure contains 155.\" .Va dls_cnt 156.\" .Vt Dl_serpath 157.\" entries. 158.\" Each entry's 159.\" .Va dlp_name 160.\" field points to the search path. 161.\" The corresponding 162.\" .Va dlp_info 163.\" field contains one of more flags indicating the origin of the path (see the 164.\" .Dv LA_SER_* 165.\" flags defined in the 166.\" .In link.h 167.\" header file). 168.\" See 169.\" .Sx EXAMPLES , 170.\" example 2, for a usage example. 171.\" .It Dv RTLD_DI_SERINFOSIZE 172.\" Initialize a 173.\" .Vt Dl_serinfo 174.\" structure for use in a 175.\" .Dv RTLD_DI_SERINFO 176.\" request. 177.\" Both the 178.\" .Va dls_cnt 179.\" and 180.\" .Va dls_size 181.\" fields are returned to indicate the number of search paths applicable 182.\" to the handle, and the total size of a 183.\" .Vt Dl_serinfo 184.\" buffer required to hold 185.\" .Va dls_cnt 186.\" .Vt Dl_serpath 187.\" entries and the associated search path strings. 188.\" See 189.\" .Sx EXAMPLES , 190.\" example 2, for a usage example. 191.\" .It Va RTLD_DI_ORIGIN 192.\" Retrieve the origin of the dynamic object associated with the handle. 193.\" On successful return, 194.\" .Fa p 195.\" argument is filled with the 196.\" .Vt char 197.\" pointer 198.\" .Pq Fa "char *p" . 199.El 200.Sh RETURN VALUES 201The 202.Fn dlinfo 203function returns 0 on success, or \-1 if an error occurred. 204Whenever an error has been detected, a message detailing it can 205be retrieved via a call to 206.Xr dlerror 3 . 207.Sh EXAMPLES 208Using 209.Fn dlinfo 210to retrieve 211.Vt Link_map 212structure. 213.Pp 214The following example shows how dynamic library can detect the list 215of shared libraries loaded after caller's one. 216For simplicity, error checking has been omitted. 217.Bd -literal -offset indent 218Link_map *map; 219 220dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map); 221 222while (map != NULL) { 223 printf("%p: %s\\n", map->l_addr, map->l_name); 224 map = map->l_next; 225} 226.Ed 227.\" .Pp 228.\" Example 2: Using 229.\" .Fn dlinfo 230.\" to retrieve the library search paths. 231.\" .Pp 232.\" The following example shows how a dynamic object can inspect the library 233.\" search paths that would be used to locate a simple filename with 234.\" .Xr dlopen 3 . 235.\" For simplicity, error checking has been omitted. 236.\" .Bd -literal -offset indent 237.\" Dl_serinfo _info, *info = &_info; 238.\" Dl_serpath *path; 239.\" unsigned int cnt; 240.\" 241.\" /* determine search path count and required buffer size */ 242.\" dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info); 243.\" 244.\" /* allocate new buffer and initialize */ 245.\" info = malloc(_info.dls_size); 246.\" info->dls_size = _info.dls_size; 247.\" info->dls_cnt = _info.dls_cnt; 248.\" 249.\" /* obtain search path information */ 250.\" dlinfo(RTLD_SELF, RTLD_DI_SERINFO, (void *)info); 251.\" 252.\" path = &info->dls_serpath[0]; 253.\" 254.\" for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) { 255.\" (void) printf("%2d: %s\\n", cnt, path->dls_name); 256.\" } 257.\" .Ed 258.Sh SEE ALSO 259.Xr rtld 1 , 260.Xr dladdr 3 , 261.Xr dlopen 3 , 262.Xr dlsym 3 263.Sh HISTORY 264The 265.Fn dlinfo 266function first appeared in the Solaris operating system. 267In 268.Nx , 269it first appeared in 270.Nx 5.1 . 271.Sh AUTHORS 272.An -nosplit 273The 274.Nx 275implementation of the 276.Fn dlinfo 277function was written by 278.An Antti Kantee Aq Mt pooka@NetBSD.org . 279.Pp 280The manual page for this function was written by 281.An Alexey Zelkin Aq Mt phantom@FreeBSD.org 282and adapted to 283.Nx 284by 285.An Kamil Rytarowski Aq Mt kamil@NetBSD.org . 286