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