xref: /freebsd/lib/libc/gen/dlinfo.3 (revision fe08efe680f6705e0c60beabe3e39629c655e743)
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