Add manual page for dlinfo(3). It's still need some work and add

examples, but it's better than nothing already.

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 .