18647a1edSAlexey Zelkin.\" 28647a1edSAlexey Zelkin.\" Copyright (c) 2003 Alexey Zelkin <phantom@FreeBSD.org> 38647a1edSAlexey Zelkin.\" All rights reserved. 48647a1edSAlexey Zelkin.\" 58647a1edSAlexey Zelkin.\" Redistribution and use in source and binary forms, with or without 68647a1edSAlexey Zelkin.\" modification, are permitted provided that the following conditions 78647a1edSAlexey Zelkin.\" are met: 88647a1edSAlexey Zelkin.\" 1. Redistributions of source code must retain the above copyright 98647a1edSAlexey Zelkin.\" notice, this list of conditions and the following disclaimer. 108647a1edSAlexey Zelkin.\" 2. Redistributions in binary form must reproduce the above copyright 118647a1edSAlexey Zelkin.\" notice, this list of conditions and the following disclaimer in the 128647a1edSAlexey Zelkin.\" documentation and/or other materials provided with the distribution. 138647a1edSAlexey Zelkin.\" 148647a1edSAlexey Zelkin.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 158647a1edSAlexey Zelkin.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 168647a1edSAlexey Zelkin.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 178647a1edSAlexey Zelkin.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 188647a1edSAlexey Zelkin.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 198647a1edSAlexey Zelkin.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 208647a1edSAlexey Zelkin.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 218647a1edSAlexey Zelkin.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 228647a1edSAlexey Zelkin.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 238647a1edSAlexey Zelkin.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 248647a1edSAlexey Zelkin.\" SUCH DAMAGE. 258647a1edSAlexey Zelkin.\" 268647a1edSAlexey Zelkin.\" $FreeBSD$ 278647a1edSAlexey Zelkin.\" 288647a1edSAlexey Zelkin.Dd February 14, 2003 298647a1edSAlexey Zelkin.Os 308647a1edSAlexey Zelkin.Dt DLINFO 3 318647a1edSAlexey Zelkin.Sh NAME 328647a1edSAlexey Zelkin.Nm dlinfo 338647a1edSAlexey Zelkin.Nd information about dynamically loaded object 348647a1edSAlexey Zelkin.Sh LIBRARY 358647a1edSAlexey Zelkin.Lb libc 368647a1edSAlexey Zelkin.Sh SYNOPSIS 378647a1edSAlexey Zelkin.In link.h 388647a1edSAlexey Zelkin.In dlfcn.h 398647a1edSAlexey Zelkin.Ft int 400e35e492SRuslan Ermilov.Fn dlinfo "void * restrict handle" "int request" "void * restrict p" 418647a1edSAlexey Zelkin.Sh DESCRIPTION 428647a1edSAlexey ZelkinThe 438647a1edSAlexey Zelkin.Fn dlinfo 448647a1edSAlexey Zelkinfunction provides information about dynamically loaded object. 458647a1edSAlexey ZelkinThe action taken by 468647a1edSAlexey Zelkin.Fn dlinfo 478647a1edSAlexey Zelkinand exact meaning and type of 488647a1edSAlexey Zelkin.Fa p 498647a1edSAlexey Zelkinargument depend on value of the 508647a1edSAlexey Zelkin.Fa request 518647a1edSAlexey Zelkinargument provided by caller. 528647a1edSAlexey Zelkin.Pp 530e35e492SRuslan ErmilovThe 548647a1edSAlexey Zelkin.Fa handle 550e35e492SRuslan Ermilovargument is either the value returned from the 560e35e492SRuslan Ermilov.Xr dlopen 3 578647a1edSAlexey Zelkinfunction call or special handle 588647a1edSAlexey Zelkin.Dv RTLD_SELF . 590e35e492SRuslan ErmilovIf 600e35e492SRuslan Ermilov.Fa handle 610e35e492SRuslan Ermilovis the value returned from 620e35e492SRuslan Ermilov.Xr dlopen 3 , 630e35e492SRuslan Ermilovthe information returned by the 648647a1edSAlexey Zelkin.Fn dlinfo 650e35e492SRuslan Ermilovfunction pertains to the specified object. 668647a1edSAlexey ZelkinIf handle is the special handle 678647a1edSAlexey Zelkin.Dv RTLD_SELF , 688647a1edSAlexey Zelkinthe information returned pertains to the caller itself. 698647a1edSAlexey Zelkin.Pp 700e35e492SRuslan ErmilovPossible values for the 718647a1edSAlexey Zelkin.Fa request 720e35e492SRuslan Ermilovargument are: 730e35e492SRuslan Ermilov.Bl -tag -width indent 740e35e492SRuslan Ermilov.It Dv RTLD_DI_LINKMAP 750e35e492SRuslan ErmilovRetrieve the 760e35e492SRuslan Ermilov.Vt Link_map 770e35e492SRuslan Ermilov.Pq Vt "struct link_map" 780e35e492SRuslan Ermilovstructure pointer for the specified 790e35e492SRuslan Ermilov.Fa handle . 800e35e492SRuslan ErmilovOn successful return, the 818647a1edSAlexey Zelkin.Fa p 820e35e492SRuslan Ermilovargument is filled with the pointer to the 830e35e492SRuslan Ermilov.Vt Link_map 840e35e492SRuslan Ermilovstructure 850e35e492SRuslan Ermilov.Pq Fa "Link_map **p" 860e35e492SRuslan Ermilovdescribing a shared object specified by the 878647a1edSAlexey Zelkin.Fa handle 888647a1edSAlexey Zelkinargument. 890e35e492SRuslan ErmilovThe 900e35e492SRuslan Ermilov.Vt Link_map 910e35e492SRuslan Ermilovstuctures are maintained as a doubly linked list by 920e35e492SRuslan Ermilov.Xr ld.so 1 , 930e35e492SRuslan Ermilovin the same order as 940e35e492SRuslan Ermilov.Xr dlopen 3 958647a1edSAlexey Zelkinand 960e35e492SRuslan Ermilov.Xr dlclose 3 978647a1edSAlexey Zelkinare called. 988647a1edSAlexey ZelkinSee 990e35e492SRuslan Ermilov.Sx EXAMPLES , 1000e35e492SRuslan Ermilovexample 1. 1016bc55edbSAlexey Zelkin.Pp 1026bc55edbSAlexey ZelkinThe 1030e35e492SRuslan Ermilov.Vt Link_map 1040e35e492SRuslan Ermilovstructure is defined in 105fe08efe6SRuslan Ermilov.In link.h 1060e35e492SRuslan Ermilovand has the following members: 1070e35e492SRuslan Ermilov.Bd -literal -offset indent 1086bc55edbSAlexey Zelkincaddr_t l_addr; /* Base Address of library */ 1096bc55edbSAlexey Zelkinconst char *l_name; /* Absolute Path to Library */ 1106bc55edbSAlexey Zelkinconst void *l_ld; /* Pointer to .dynamic in memory */ 1110e35e492SRuslan Ermilovstruct link_map *l_next, /* linked list of mapped libs */ 1126bc55edbSAlexey Zelkin *l_prev; 1136bc55edbSAlexey Zelkin.Ed 1140e35e492SRuslan Ermilov.Bl -tag -width ".Va l_addr" 1150e35e492SRuslan Ermilov.It Va l_addr 1166bc55edbSAlexey ZelkinThe base address of the object loaded into memory. 1170e35e492SRuslan Ermilov.It Va l_name 1180e35e492SRuslan ErmilovThe full name of the loaded shared object. 1190e35e492SRuslan Ermilov.It Va l_ld 1200e35e492SRuslan ErmilovThe address of the dynamic linking information segment 1210e35e492SRuslan Ermilov.Pq Dv PT_DYNAMIC 1226bc55edbSAlexey Zelkinloaded into memory. 1230e35e492SRuslan Ermilov.It Va l_next 1240e35e492SRuslan ErmilovThe next 1250e35e492SRuslan Ermilov.Vt Link_map 1260e35e492SRuslan Ermilovstructure on the link-map list. 1270e35e492SRuslan Ermilov.It Va l_prev 1280e35e492SRuslan ErmilovThe previous 1290e35e492SRuslan Ermilov.Vt Link_map 1300e35e492SRuslan Ermilovstructure on the link-map list. 1316bc55edbSAlexey Zelkin.El 1320e35e492SRuslan Ermilov.It Dv RTLD_DI_SERINFO 1330e35e492SRuslan ErmilovRetrieve the library search paths associated with the given 1348647a1edSAlexey Zelkin.Fa handle 1358647a1edSAlexey Zelkinargument. 1368647a1edSAlexey ZelkinThe 1378647a1edSAlexey Zelkin.Fa p 1388647a1edSAlexey Zelkinargument should point to 1390e35e492SRuslan Ermilov.Vt Dl_serinfo 1408647a1edSAlexey Zelkinstructure buffer 1410e35e492SRuslan Ermilov.Pq Fa "Dl_serinfo *p" . 1420e35e492SRuslan ErmilovThe 1430e35e492SRuslan Ermilov.Vt Dl_serinfo 1440e35e492SRuslan Ermilovstructure must be initialized first with the 1458647a1edSAlexey Zelkin.Dv RTLD_DI_SERINFOSIZE 1468647a1edSAlexey Zelkinrequest. 1478647a1edSAlexey Zelkin.Pp 1488647a1edSAlexey ZelkinThe returned 1490e35e492SRuslan Ermilov.Vt Dl_serinfo 1508647a1edSAlexey Zelkinstructure contains 1510e35e492SRuslan Ermilov.Va dls_cnt 1520e35e492SRuslan Ermilov.Vt Dl_serpath 1538647a1edSAlexey Zelkinentries. 1548647a1edSAlexey ZelkinEach entry's 1550e35e492SRuslan Ermilov.Va dlp_name 1568647a1edSAlexey Zelkinfield points to the search path. 1578647a1edSAlexey ZelkinThe corresponding 1580e35e492SRuslan Ermilov.Va dlp_info 1598647a1edSAlexey Zelkinfield contains one of more flags indicating the origin of the path (see the 1608647a1edSAlexey Zelkin.Dv LA_SER_* 1610e35e492SRuslan Ermilovflags defined in the 162fe08efe6SRuslan Ermilov.In link.h 1630e35e492SRuslan Ermilovheader file). 1648647a1edSAlexey ZelkinSee 1650e35e492SRuslan Ermilov.Sx EXAMPLES , 1660e35e492SRuslan Ermilovexample 2, for a usage example. 1670e35e492SRuslan Ermilov.It Dv RTLD_DI_SERINFOSIZE 1688647a1edSAlexey ZelkinInitialize a 1690e35e492SRuslan Ermilov.Vt Dl_serinfo 1708647a1edSAlexey Zelkinstructure for use in a 1718647a1edSAlexey Zelkin.Dv RTLD_DI_SERINFO 1728647a1edSAlexey Zelkinrequest. 1738647a1edSAlexey ZelkinBoth the 1740e35e492SRuslan Ermilov.Va dls_cnt 1758647a1edSAlexey Zelkinand 1760e35e492SRuslan Ermilov.Va dls_size 1778647a1edSAlexey Zelkinfields are returned to indicate the number of search paths applicable 1788647a1edSAlexey Zelkinto the handle, and the total size of a 1790e35e492SRuslan Ermilov.Vt Dl_serinfo 1808647a1edSAlexey Zelkinbuffer required to hold 1810e35e492SRuslan Ermilov.Va dls_cnt 1820e35e492SRuslan Ermilov.Vt Dl_serpath 1838647a1edSAlexey Zelkinentries and the associated search path strings. 1848647a1edSAlexey ZelkinSee 1850e35e492SRuslan Ermilov.Sx EXAMPLES , 1860e35e492SRuslan Ermilovexample 2, for a usage example. 1870e35e492SRuslan Ermilov.It Va RTLD_DI_ORIGIN 1888647a1edSAlexey ZelkinRetrieve the origin of the dynamic object associated with the handle. 1890e35e492SRuslan ErmilovOn successful return, 1908647a1edSAlexey Zelkin.Fa p 1910e35e492SRuslan Ermilovargument is filled with the 1920e35e492SRuslan Ermilov.Vt char 1938647a1edSAlexey Zelkinpointer 1940e35e492SRuslan Ermilov.Pq Fa "char *p" . 1958647a1edSAlexey Zelkin.El 1968647a1edSAlexey Zelkin.Sh EXAMPLES 197f7344926SAlexey ZelkinExample 1: Using 198f7344926SAlexey Zelkin.Fn dlinfo 1990e35e492SRuslan Ermilovto retrieve 2000e35e492SRuslan Ermilov.Vt Link_map 2010e35e492SRuslan Ermilovstructure. 202f7344926SAlexey Zelkin.Pp 203f7344926SAlexey ZelkinThe following example shows how dynamic library can detect the list 204f7344926SAlexey Zelkinof shared libraries loaded after caller's one. 205f7344926SAlexey ZelkinFor simplicity, error checking has been omitted. 2060e35e492SRuslan Ermilov.Bd -literal -offset indent 207f7344926SAlexey ZelkinLink_map *map; 208f7344926SAlexey Zelkin 209f7344926SAlexey Zelkindlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map); 210f7344926SAlexey Zelkin 211f7344926SAlexey Zelkinwhile (map != NULL) { 212aba60fa6SRuslan Ermilov printf("%p: %s\\n", map->l_addr, map->l_name); 213f7344926SAlexey Zelkin map = map->l_next; 214f7344926SAlexey Zelkin} 215f7344926SAlexey Zelkin.Ed 216f7344926SAlexey Zelkin.Pp 217f7344926SAlexey ZelkinExample 2: Using 218f7344926SAlexey Zelkin.Fn dlinfo 219f7344926SAlexey Zelkinto retrieve the library search paths. 220f7344926SAlexey Zelkin.Pp 221f7344926SAlexey ZelkinThe following example shows how a dynamic object can inspect the library 222f7344926SAlexey Zelkinsearch paths that would be used to locate a simple filename with 2230e35e492SRuslan Ermilov.Xr dlopen 3 . 224f7344926SAlexey ZelkinFor simplicity, error checking has been omitted. 2250e35e492SRuslan Ermilov.Bd -literal -offset indent 226f7344926SAlexey ZelkinDl_serinfo _info, *info = &_info; 227f7344926SAlexey ZelkinDl_serpath *path; 228f7344926SAlexey Zelkinunsigned int cnt; 229f7344926SAlexey Zelkin 230f7344926SAlexey Zelkin/* determine search path count and required buffer size */ 231f7344926SAlexey Zelkindlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info); 232f7344926SAlexey Zelkin 233f7344926SAlexey Zelkin/* allocate new buffer and initialize */ 234f7344926SAlexey Zelkininfo = malloc(_info.dls_size); 235f7344926SAlexey Zelkininfo->dls_size = _info.dls_size; 236f7344926SAlexey Zelkininfo->dls_cnt = _info.dls_cnt; 237f7344926SAlexey Zelkin 238f7344926SAlexey Zelkin/* obtain sarch path information */ 239f7344926SAlexey Zelkindlinfo(RTLD_SELF, RTLD_DI_SERINFO, (void *)info); 240f7344926SAlexey Zelkin 241f7344926SAlexey Zelkinpath = &info->dls_serpath[0]; 242f7344926SAlexey Zelkin 243f7344926SAlexey Zelkinfor (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) { 244aba60fa6SRuslan Ermilov (void) printf("%2d: %s\\n", cnt, path->dls_name); 245f7344926SAlexey Zelkin} 246f7344926SAlexey Zelkin.Ed 2478647a1edSAlexey Zelkin.Sh RETURN VALUES 248b43dc211SPhilippe CharnierThe 2498647a1edSAlexey Zelkin.Fn dlinfo 2500e35e492SRuslan Ermilovfunction returns 0 on success, or \-1 if an error occured. 2518647a1edSAlexey ZelkinWhenever an error has been detected, a message detailing it can 2528647a1edSAlexey Zelkinbe retrieved via a call to 2530e35e492SRuslan Ermilov.Xr dlerror 3 . 2548647a1edSAlexey Zelkin.Sh SEE ALSO 2558647a1edSAlexey Zelkin.Xr rtld 1 , 2568647a1edSAlexey Zelkin.Xr dladdr 3 , 2578647a1edSAlexey Zelkin.Xr dlopen 3 , 2588647a1edSAlexey Zelkin.Xr dlsym 3 2598647a1edSAlexey Zelkin.Sh HISTORY 2608647a1edSAlexey ZelkinThe 2618647a1edSAlexey Zelkin.Fn dlinfo 2628647a1edSAlexey Zelkinfunction first appeared in the Solaris operating system. 2638647a1edSAlexey ZelkinIn 2640e35e492SRuslan Ermilov.Fx , 2658647a1edSAlexey Zelkinit first appeared in 2668647a1edSAlexey Zelkin.Fx 4.8 . 2678647a1edSAlexey Zelkin.Sh AUTHORS 2680e35e492SRuslan Ermilov.An -nosplit 2698647a1edSAlexey ZelkinThe 2706bc55edbSAlexey Zelkin.Fx 2710e35e492SRuslan Ermilovimplementation of the 2728647a1edSAlexey Zelkin.Fn dlinfo 2738647a1edSAlexey Zelkinfunction was originally written by 2748647a1edSAlexey Zelkin.An Alexey Zelkin 2758647a1edSAlexey Zelkin.Aq phantom@FreeBSD.org 2768647a1edSAlexey Zelkinand later extended and improved by 2778647a1edSAlexey Zelkin.An Alexander Kabaev 2788647a1edSAlexey Zelkin.Aq kan@FreeBSD.org . 2798647a1edSAlexey Zelkin.Pp 2808647a1edSAlexey ZelkinThe manual page for this function was written by 2818647a1edSAlexey Zelkin.An Alexey Zelkin 2828647a1edSAlexey Zelkin.Aq phantom@FreeBSD.org . 283