xref: /freebsd/lib/libc/gen/dlinfo.3 (revision 6bc55edb4cf8e617ca5a959beff93e0021e881b5)
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
408647a1edSAlexey Zelkin.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
538647a1edSAlexey ZelkinA
548647a1edSAlexey Zelkin.Fa handle
558647a1edSAlexey Zelkinargument is either the value returned from a
568647a1edSAlexey Zelkin.Fn dlopen
578647a1edSAlexey Zelkinfunction call or special handle
588647a1edSAlexey Zelkin.Dv RTLD_SELF .
598647a1edSAlexey ZelkinIf handle is the value returned from
608647a1edSAlexey Zelkin.Fn dlopen
618647a1edSAlexey Zelkincall, the information returned by the
628647a1edSAlexey Zelkin.Fn dlinfo
638647a1edSAlexey Zelkinfunction is pertains the specified object.
648647a1edSAlexey ZelkinIf handle is the special handle
658647a1edSAlexey Zelkin.Dv RTLD_SELF ,
668647a1edSAlexey Zelkinthe information returned pertains to the caller itself.
678647a1edSAlexey Zelkin.Pp
688647a1edSAlexey ZelkinThe following are possible values for
698647a1edSAlexey Zelkin.Fa request
708647a1edSAlexey Zelkinargument to be passed into
718647a1edSAlexey Zelkin.Fn dlinfo :
728647a1edSAlexey Zelkin.Bl -tag -width Ds
738647a1edSAlexey Zelkin.It RTLD_DI_LINKMAP
748647a1edSAlexey ZelkinRetrieve the Link_map (or
758647a1edSAlexey Zelkin.Ft struct link_map )
768647a1edSAlexey Zelkinstructure pointer for
778647a1edSAlexey Zelkin.Fa handle
788647a1edSAlexey Zelkinspecified.
798647a1edSAlexey ZelkinOn successful return the
808647a1edSAlexey Zelkin.Fa p
818647a1edSAlexey Zelkinargument is filled with pointer to Link_map structure
828647a1edSAlexey Zelkin.Ft ( Link_map **p )
838647a1edSAlexey Zelkindescribing shared object specified by
848647a1edSAlexey Zelkin.Fa handle
858647a1edSAlexey Zelkinargument.
868647a1edSAlexey Zelkin.Ft Link_map
878647a1edSAlexey Zelkinstuctures are maintained as double-linked list by
888647a1edSAlexey Zelkin.Xr ld.so 1
898647a1edSAlexey Zelkinin same order as
908647a1edSAlexey Zelkin.Fn dlopen
918647a1edSAlexey Zelkinand
928647a1edSAlexey Zelkin.Fn dlclose
938647a1edSAlexey Zelkinare called.
948647a1edSAlexey ZelkinSee
958647a1edSAlexey Zelkin.Sx EXAMPLES
966bc55edbSAlexey Zelkin(Example 1.)
976bc55edbSAlexey Zelkin.Pp
986bc55edbSAlexey ZelkinThe
996bc55edbSAlexey Zelkin.Ft Link_map
1006bc55edbSAlexey Zelkinstructure is defined in <link.h> and have following members:
1016bc55edbSAlexey Zelkin.Pp
1026bc55edbSAlexey Zelkin.Bd -literal
1036bc55edbSAlexey Zelkin  caddr_t         l_addr;    /* Base Address of library */
1046bc55edbSAlexey Zelkin  const char      *l_name;   /* Absolute Path to Library */
1056bc55edbSAlexey Zelkin  const void      *l_ld;     /* Pointer to .dynamic in memory */
1066bc55edbSAlexey Zelkin  struct link_map *l_next,   /* linked list of of mapped libs */
1076bc55edbSAlexey Zelkin                  *l_prev;
1086bc55edbSAlexey Zelkin.Ed
1096bc55edbSAlexey Zelkin.Bl -tag -width Ds
1106bc55edbSAlexey Zelkin.It l_addr
1116bc55edbSAlexey ZelkinThe base address of the object loaded into memory.
1126bc55edbSAlexey Zelkin.It l_name
1136bc55edbSAlexey ZelkinThe full name of loaded shared object.
1146bc55edbSAlexey Zelkin.It l_ld
1156bc55edbSAlexey ZelkinThe address of dynamic linking information segment
1166bc55edbSAlexey Zelkin.Dv ( PT_DYNAMIC )
1176bc55edbSAlexey Zelkinloaded into memory.
1186bc55edbSAlexey Zelkin.It l_next
1196bc55edbSAlexey ZelkinThe next Link_map structure on the link-map list.
1206bc55edbSAlexey Zelkin.It l_prev
1216bc55edbSAlexey ZelkinThe previous Link_map structure on the link-map list.
1226bc55edbSAlexey Zelkin.El
1238647a1edSAlexey Zelkin.It RTLD_DI_SERINFO
1248647a1edSAlexey ZelkinRetrieve the library search paths associated with given
1258647a1edSAlexey Zelkin.Fa handle
1268647a1edSAlexey Zelkinargument.
1278647a1edSAlexey ZelkinThe
1288647a1edSAlexey Zelkin.Fa p
1298647a1edSAlexey Zelkinargument should point to
1308647a1edSAlexey Zelkin.Ft Dl_serinfo
1318647a1edSAlexey Zelkinstructure buffer
1328647a1edSAlexey Zelkin.Fa ( Dl_serinfo *p ) .
1338647a1edSAlexey Zelkin.Ft Dl_serinfo
1348647a1edSAlexey Zelkinstructure must be initialized first with a
1358647a1edSAlexey Zelkin.Dv RTLD_DI_SERINFOSIZE
1368647a1edSAlexey Zelkinrequest.
1378647a1edSAlexey Zelkin.Pp
1388647a1edSAlexey ZelkinThe returned
1398647a1edSAlexey Zelkin.Ft Dl_serinfo
1408647a1edSAlexey Zelkinstructure contains
1418647a1edSAlexey Zelkin.Dv dls_cnt
1428647a1edSAlexey Zelkin.Ft Dl_serpath
1438647a1edSAlexey Zelkinentries.
1448647a1edSAlexey ZelkinEach entry's
1458647a1edSAlexey Zelkin.Dv dlp_name
1468647a1edSAlexey Zelkinfield points to the search path.
1478647a1edSAlexey ZelkinThe corresponding
1488647a1edSAlexey Zelkin.Dv dlp_info
1498647a1edSAlexey Zelkinfield contains one of more flags indicating the origin of the path (see the
1508647a1edSAlexey Zelkin.Dv LA_SER_*
1518647a1edSAlexey Zelkinflags defined in <link.h> header file.)
1528647a1edSAlexey ZelkinSee
1538647a1edSAlexey Zelkin.Sx EXAMPLES
1548647a1edSAlexey Zelkin(Example 2) for usage example.
1558647a1edSAlexey Zelkin.It RTLD_DI_SERINFOSIZE
1568647a1edSAlexey ZelkinInitialize a
1578647a1edSAlexey Zelkin.Ft Dl_serinfo
1588647a1edSAlexey Zelkinstructure for use in a
1598647a1edSAlexey Zelkin.Dv RTLD_DI_SERINFO
1608647a1edSAlexey Zelkinrequest.
1618647a1edSAlexey ZelkinBoth the
1628647a1edSAlexey Zelkin.Dv dls_cnt
1638647a1edSAlexey Zelkinand
1648647a1edSAlexey Zelkin.Dv dls_size
1658647a1edSAlexey Zelkinfields are returned to indicate the number of search paths applicable
1668647a1edSAlexey Zelkinto the handle, and the total size of a
1678647a1edSAlexey Zelkin.Ft Dl_serinfo
1688647a1edSAlexey Zelkinbuffer required to hold
1698647a1edSAlexey Zelkin.Dv dls_cnt
1708647a1edSAlexey Zelkin.Ft Dl_serpath
1718647a1edSAlexey Zelkinentries and the associated search path strings.
1728647a1edSAlexey ZelkinSee
1738647a1edSAlexey Zelkin.Sx EXAMPLES
1748647a1edSAlexey Zelkin(Example 2) for usage example.
1758647a1edSAlexey Zelkin.It RTLD_DI_ORIGIN
1768647a1edSAlexey ZelkinRetrieve the origin of the dynamic object associated with the handle.
1778647a1edSAlexey ZelkinOn successful return
1788647a1edSAlexey Zelkin.Fa p
1798647a1edSAlexey Zelkinargument is filled with
1808647a1edSAlexey Zelkin.Ft char
1818647a1edSAlexey Zelkinpointer
1828647a1edSAlexey Zelkin.Ft ( char *p ) .
1838647a1edSAlexey Zelkin.El
1848647a1edSAlexey Zelkin.Sh EXAMPLES
1858647a1edSAlexey ZelkinTo be continued
1868647a1edSAlexey Zelkin.Sh RETURN VALUES
1878647a1edSAlexey Zelkin.Fn dlinfo
1888647a1edSAlexey Zelkinreturns 0 on success, or -1 if error occured.
1898647a1edSAlexey ZelkinWhenever an error has been detected, a message detailing it can
1908647a1edSAlexey Zelkinbe retrieved via a call to
1918647a1edSAlexey Zelkin.Fn dlerror .
1928647a1edSAlexey Zelkin.Sh SEE ALSO
1938647a1edSAlexey Zelkin.Xr rtld 1 ,
1948647a1edSAlexey Zelkin.Xr dladdr 3 ,
1958647a1edSAlexey Zelkin.Xr dlopen 3 ,
1968647a1edSAlexey Zelkin.Xr dlsym 3
1978647a1edSAlexey Zelkin.Sh HISTORY
1988647a1edSAlexey ZelkinThe
1998647a1edSAlexey Zelkin.Fn dlinfo
2008647a1edSAlexey Zelkinfunction first appeared in the Solaris operating system.
2018647a1edSAlexey ZelkinIn
2028647a1edSAlexey Zelkin.Fx
2038647a1edSAlexey Zelkinit first appeared in
2048647a1edSAlexey Zelkin.Fx 4.8 .
2058647a1edSAlexey Zelkin.Sh AUTHORS
2068647a1edSAlexey ZelkinThe
2076bc55edbSAlexey Zelkin.Fx
2086bc55edbSAlexey Zelkinimplementation of
2098647a1edSAlexey Zelkin.Fn dlinfo
2108647a1edSAlexey Zelkinfunction was originally written by
2118647a1edSAlexey Zelkin.An Alexey Zelkin
2128647a1edSAlexey Zelkin.Aq phantom@FreeBSD.org
2138647a1edSAlexey Zelkinand later extended and improved by
2148647a1edSAlexey Zelkin.An Alexander Kabaev
2158647a1edSAlexey Zelkin.Aq kan@FreeBSD.org .
2168647a1edSAlexey Zelkin.Pp
2178647a1edSAlexey ZelkinThe manual page for this function was written by
2188647a1edSAlexey Zelkin.An Alexey Zelkin
2198647a1edSAlexey Zelkin.Aq phantom@FreeBSD.org .
220