diff options
Diffstat (limited to 'lib/libc/gen/dlinfo.3')
-rw-r--r-- | lib/libc/gen/dlinfo.3 | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/lib/libc/gen/dlinfo.3 b/lib/libc/gen/dlinfo.3 new file mode 100644 index 0000000..d8d9fb8 --- /dev/null +++ b/lib/libc/gen/dlinfo.3 @@ -0,0 +1,191 @@ +.\" +.\" Copyright (c) 2003 Alexey Zelkin <phantom@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 14, 2003 +.Os +.Dt DLINFO 3 +.Sh NAME +.Nm dlinfo +.Nd information about dynamically loaded object +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In link.h +.In dlfcn.h +.Ft int +.Fn dlinfo "void * __restrict handle" "int request" "void * __restrict p" +.Sh DESCRIPTION +The +.Fn dlinfo +function provides information about dynamically loaded object. +The action taken by +.Fn dlinfo +and exact meaning and type of +.Fa p +argument depend on value of the +.Fa request +argument provided by caller. +.Pp +A +.Fa handle +argument is either the value returned from a +.Fn dlopen +function call or special handle +.Dv RTLD_SELF . +If handle is the value returned from +.Fn dlopen +call, the information returned by the +.Fn dlinfo +function is pertains the specified object. +If handle is the special handle +.Dv RTLD_SELF , +the information returned pertains to the caller itself. +.Pp +The following are possible values for +.Fa request +argument to be passed into +.Fn dlinfo : +.Bl -tag -width Ds +.It RTLD_DI_LINKMAP +Retrieve the Link_map (or +.Ft struct link_map ) +structure pointer for +.Fa handle +specified. +On successful return the +.Fa p +argument is filled with pointer to Link_map structure +.Ft ( Link_map **p ) +describing shared object specified by +.Fa handle +argument. +.Ft Link_map +stuctures are maintained as double-linked list by +.Xr ld.so 1 +in same order as +.Fn dlopen +and +.Fn dlclose +are called. +See +.Sx EXAMPLES +(Example 1) +.It RTLD_DI_SERINFO +Retrieve the library search paths associated with given +.Fa handle +argument. +The +.Fa p +argument should point to +.Ft Dl_serinfo +structure buffer +.Fa ( Dl_serinfo *p ) . +.Ft Dl_serinfo +structure must be initialized first with a +.Dv RTLD_DI_SERINFOSIZE +request. +.Pp +The returned +.Ft Dl_serinfo +structure contains +.Dv dls_cnt +.Ft Dl_serpath +entries. +Each entry's +.Dv dlp_name +field points to the search path. +The corresponding +.Dv dlp_info +field contains one of more flags indicating the origin of the path (see the +.Dv LA_SER_* +flags defined in <link.h> header file.) +See +.Sx EXAMPLES +(Example 2) for usage example. +.It RTLD_DI_SERINFOSIZE +Initialize a +.Ft Dl_serinfo +structure for use in a +.Dv RTLD_DI_SERINFO +request. +Both the +.Dv dls_cnt +and +.Dv dls_size +fields are returned to indicate the number of search paths applicable +to the handle, and the total size of a +.Ft Dl_serinfo +buffer required to hold +.Dv dls_cnt +.Ft Dl_serpath +entries and the associated search path strings. +See +.Sx EXAMPLES +(Example 2) for usage example. +.It RTLD_DI_ORIGIN +Retrieve the origin of the dynamic object associated with the handle. +On successful return +.Fa p +argument is filled with +.Ft char +pointer +.Ft ( char *p ) . +.El +.Sh EXAMPLES +To be continued +.Sh RETURN VALUES +.Fn dlinfo +returns 0 on success, or -1 if error occured. +Whenever an error has been detected, a message detailing it can +be retrieved via a call to +.Fn dlerror . +.Sh SEE ALSO +.Xr rtld 1 , +.Xr dladdr 3 , +.Xr dlopen 3 , +.Xr dlsym 3 +.Sh HISTORY +The +.Fn dlinfo +function first appeared in the Solaris operating system. +In +.Fx +it first appeared in +.Fx 4.8 . +.Sh AUTHORS +The +.Fn dlinfo +function was originally written by +.An Alexey Zelkin +.Aq phantom@FreeBSD.org +and later extended and improved by +.An Alexander Kabaev +.Aq kan@FreeBSD.org . +.Pp +The manual page for this function was written by +.An Alexey Zelkin +.Aq phantom@FreeBSD.org . |