Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Document dlinfo(3)
details: https://anonhg.NetBSD.org/src/rev/e587f33b1042
branches: trunk
changeset: 467090:e587f33b1042
user: kamil <kamil%NetBSD.org@localhost>
date: Mon Jan 13 08:25:02 2020 +0000
description:
Document dlinfo(3)
Man-page taken from FreeBSD.
diffstat:
distrib/sets/lists/comp/mi | 5 +-
share/man/man3/Makefile | 4 +-
share/man/man3/dlinfo.3 | 283 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 289 insertions(+), 3 deletions(-)
diffs (truncated from 338 to 300 lines):
diff -r ce9c8f1ef5ec -r e587f33b1042 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Mon Jan 13 03:34:05 2020 +0000
+++ b/distrib/sets/lists/comp/mi Mon Jan 13 08:25:02 2020 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2299 2019/12/23 06:45:36 maxv Exp $
+# $NetBSD: mi,v 1.2300 2020/01/13 08:25:02 kamil Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -6472,6 +6472,7 @@
./usr/share/man/cat3/dlctl.0 comp-c-catman .cat
./usr/share/man/cat3/dlerror.0 comp-c-catman .cat
./usr/share/man/cat3/dlfcn.0 comp-c-catman .cat
+./usr/share/man/cat3/dlinfo.0 comp-c-catman .cat
./usr/share/man/cat3/dlopen.0 comp-c-catman .cat
./usr/share/man/cat3/dlsym.0 comp-c-catman .cat
./usr/share/man/cat3/dlvsym.0 comp-c-catman .cat
@@ -14502,6 +14503,7 @@
./usr/share/man/html3/dlctl.html comp-c-htmlman html
./usr/share/man/html3/dlerror.html comp-c-htmlman html
./usr/share/man/html3/dlfcn.html comp-c-htmlman html
+./usr/share/man/html3/dlinfo.html comp-c-htmlman html
./usr/share/man/html3/dlopen.html comp-c-htmlman html
./usr/share/man/html3/dlsym.html comp-c-htmlman html
./usr/share/man/html3/dlvsym.html comp-c-htmlman html
@@ -22466,6 +22468,7 @@
./usr/share/man/man3/dlctl.3 comp-c-man .man
./usr/share/man/man3/dlerror.3 comp-c-man .man
./usr/share/man/man3/dlfcn.3 comp-c-man .man
+./usr/share/man/man3/dlinfo.3 comp-c-man .man
./usr/share/man/man3/dlopen.3 comp-c-man .man
./usr/share/man/man3/dlsym.3 comp-c-man .man
./usr/share/man/man3/dlvsym.3 comp-c-man .man
diff -r ce9c8f1ef5ec -r e587f33b1042 share/man/man3/Makefile
--- a/share/man/man3/Makefile Mon Jan 13 03:34:05 2020 +0000
+++ b/share/man/man3/Makefile Mon Jan 13 08:25:02 2020 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.89 2019/11/10 18:45:09 christos Exp $
+# $NetBSD: Makefile,v 1.90 2020/01/13 08:25:02 kamil Exp $
# @(#)Makefile 8.2 (Berkeley) 12/13/93
MAN= _DIAGASSERT.3 __CONCAT.3 __FPTRCAST.3 __UNCONST.3 __USE.3 CMSG_DATA.3 \
@@ -7,7 +7,7 @@
__builtin_return_address.3 \
__builtin_types_compatible_p.3 __insn_barrier.3 \
assert.3 attribute.3 bitmap.3 bitops.3 bits.3 bitstring.3 \
- cdefs.3 dirent.3 dlfcn.3 dl_iterate_phdr.3 end.3 \
+ cdefs.3 dirent.3 dlfcn.3 dlinfo.3 dl_iterate_phdr.3 end.3 \
fast_divide32.3 ffs32.3 gcq.3 \
ilog2.3 intro.3 inttypes.3 iso646.3 limits.3 \
makedev.3 offsetof.3 param.3 paths.3 queue.3 rbtree.3 sigevent.3 \
diff -r ce9c8f1ef5ec -r e587f33b1042 share/man/man3/dlinfo.3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man3/dlinfo.3 Mon Jan 13 08:25:02 2020 +0000
@@ -0,0 +1,283 @@
+.\" $NetBSD: dlinfo.3,v 1.1 2020/01/13 08:25:02 kamil Exp $
+.\"
+.\" Copyright (c) 2003 Alexey Zelkin <phantom%FreeBSD.org@localhost>
+.\" 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: head/lib/libc/gen/dlinfo.3 267774 2014-06-23 08:25:03Z bapt $
+.\"
+.Dd February 14, 2003
+.Dt DLINFO 3
+.Os
+.Sh NAME
+.Nm dlinfo
+.Nd information about dynamically loaded object
+.Sh LIBRARY
+(These functions are not in a library.
+They are included in every
+dynamically linked program automatically.)
+.Sh SYNOPSIS
+.In link.h
+.In dlfcn.h
+.Ft int
+.Fn dlinfo "void * handle" "int request" "void * 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
+The
+.Fa handle
+argument is either the value returned from the
+.Xr dlopen 3
+function call or special handle
+.Dv RTLD_SELF .
+If
+.Fa handle
+is the value returned from
+.Xr dlopen 3 ,
+the information returned by the
+.Fn dlinfo
+function pertains to the specified object.
+If handle is the special handle
+.Dv RTLD_SELF ,
+the information returned pertains to the caller itself.
+.Pp
+Possible values for the
+.Fa request
+argument are:
+.Bl -tag -width indent
+.It Dv RTLD_DI_LINKMAP
+Retrieve the
+.Vt Link_map
+.Pq Vt "struct link_map"
+structure pointer for the specified
+.Fa handle .
+On successful return, the
+.Fa p
+argument is filled with the pointer to the
+.Vt Link_map
+structure
+.Pq Fa "Link_map **p"
+describing a shared object specified by the
+.Fa handle
+argument.
+The
+.Vt Link_map
+structures are maintained as a doubly linked list by
+.Xr ld.so 1 ,
+in the same order as
+.Xr dlopen 3
+and
+.Xr dlclose 3
+are called.
+The
+.Vt Link_map
+structure is defined in
+.In link.h
+and has the following members:
+.Bd -literal -offset indent
+caddr_t l_addr; /* Base Address of library */
+#ifdef __mips__
+caddr_t l_offs; /* Load Offset of library */
+#endif
+const char *l_name; /* Absolute Path to Library */
+void *l_ld; /* Pointer to .dynamic in memory */
+struct link_map *l_next, /* linked list of mapped libs */
+ *l_prev;
+.Ed
+.Bl -tag -width ".Va l_addr"
+.It Va l_addr
+The base address of the object loaded into memory.
+.It Va l_name
+The full name of the loaded shared object.
+.It Va l_ld
+The address of the dynamic linking information segment
+.Pq Dv PT_DYNAMIC
+loaded into memory.
+.It Va l_next
+The next
+.Vt Link_map
+structure on the link-map list.
+.It Va l_prev
+The previous
+.Vt Link_map
+structure on the link-map list.
+.El
+.\" .It Dv RTLD_DI_SERINFO
+.\" Retrieve the library search paths associated with the given
+.\" .Fa handle
+.\" argument.
+.\" The
+.\" .Fa p
+.\" argument should point to
+.\" .Vt Dl_serinfo
+.\" structure buffer
+.\" .Pq Fa "Dl_serinfo *p" .
+.\" The
+.\" .Vt Dl_serinfo
+.\" structure must be initialized first with the
+.\" .Dv RTLD_DI_SERINFOSIZE
+.\" request.
+.\" .Pp
+.\" The returned
+.\" .Vt Dl_serinfo
+.\" structure contains
+.\" .Va dls_cnt
+.\" .Vt Dl_serpath
+.\" entries.
+.\" Each entry's
+.\" .Va dlp_name
+.\" field points to the search path.
+.\" The corresponding
+.\" .Va dlp_info
+.\" field contains one of more flags indicating the origin of the path (see the
+.\" .Dv LA_SER_*
+.\" flags defined in the
+.\" .In link.h
+.\" header file).
+.\" See
+.\" .Sx EXAMPLES ,
+.\" example 2, for a usage example.
+.\" .It Dv RTLD_DI_SERINFOSIZE
+.\" Initialize a
+.\" .Vt Dl_serinfo
+.\" structure for use in a
+.\" .Dv RTLD_DI_SERINFO
+.\" request.
+.\" Both the
+.\" .Va dls_cnt
+.\" and
+.\" .Va dls_size
+.\" fields are returned to indicate the number of search paths applicable
+.\" to the handle, and the total size of a
+.\" .Vt Dl_serinfo
+.\" buffer required to hold
+.\" .Va dls_cnt
+.\" .Vt Dl_serpath
+.\" entries and the associated search path strings.
+.\" See
+.\" .Sx EXAMPLES ,
+.\" example 2, for a usage example.
+.\" .It Va RTLD_DI_ORIGIN
+.\" Retrieve the origin of the dynamic object associated with the handle.
+.\" On successful return,
+.\" .Fa p
+.\" argument is filled with the
+.\" .Vt char
+.\" pointer
+.\" .Pq Fa "char *p" .
+.\" .El
+.Sh RETURN VALUES
+The
+.Fn dlinfo
+function returns 0 on success, or \-1 if an error occurred.
+Whenever an error has been detected, a message detailing it can
+be retrieved via a call to
+.Xr dlerror 3 .
+.Sh EXAMPLES
+Using
+.Fn dlinfo
+to retrieve
+.Vt Link_map
+structure.
+.Pp
+The following example shows how dynamic library can detect the list
+of shared libraries loaded after caller's one.
+For simplicity, error checking has been omitted.
+.Bd -literal -offset indent
+Link_map *map;
+
+dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map);
+
+while (map != NULL) {
+ printf("%p: %s\\n", map->l_addr, map->l_name);
+ map = map->l_next;
+}
+.Ed
+.\" .Pp
+.\" Example 2: Using
+.\" .Fn dlinfo
+.\" to retrieve the library search paths.
+.\" .Pp
+.\" The following example shows how a dynamic object can inspect the library
+.\" search paths that would be used to locate a simple filename with
+.\" .Xr dlopen 3 .
+.\" For simplicity, error checking has been omitted.
+.\" .Bd -literal -offset indent
+.\" Dl_serinfo _info, *info = &_info;
+.\" Dl_serpath *path;
+.\" unsigned int cnt;
+.\"
+.\" /* determine search path count and required buffer size */
+.\" dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info);
+.\"
+.\" /* allocate new buffer and initialize */
+.\" info = malloc(_info.dls_size);
+.\" info->dls_size = _info.dls_size;
+.\" info->dls_cnt = _info.dls_cnt;
Home |
Main Index |
Thread Index |
Old Index