|
 |
076f82 |
commit e4a2fb76efb45210c541ee3f8ef32f317783c3a8
|
|
|
076f82 |
Author: Florian Weimer <fweimer@redhat.com>
|
|
|
076f82 |
Date: Wed May 11 20:30:49 2022 +0200
|
|
|
076f82 |
|
|
|
076f82 |
manual: Document the dlinfo function
|
|
|
076f82 |
|
|
|
076f82 |
Reviewed-by: Carlos O'Donell <carlos@redhat.com>
|
|
|
076f82 |
Tested-by: Carlos O'Donell <carlos@rehdat.com>
|
|
|
076f82 |
(cherry picked from commit 93804a1ee084d4bdc620b2b9f91615c7da0fabe1)
|
|
|
076f82 |
|
|
|
076f82 |
Also includes partial backport of commit 5d28a8962dcb6ec056b81d730e
|
|
|
076f82 |
(the addition of manual/dynlink.texi).
|
|
|
076f82 |
|
|
|
076f82 |
diff --git a/manual/Makefile b/manual/Makefile
|
|
|
076f82 |
index e83444341e282916..31678681ef059e0f 100644
|
|
|
076f82 |
--- a/manual/Makefile
|
|
|
076f82 |
+++ b/manual/Makefile
|
|
|
076f82 |
@@ -39,7 +39,7 @@ chapters = $(addsuffix .texi, \
|
|
|
076f82 |
pipe socket terminal syslog math arith time \
|
|
|
076f82 |
resource setjmp signal startup process ipc job \
|
|
|
076f82 |
nss users sysinfo conf crypt debug threads \
|
|
|
076f82 |
- probes tunables)
|
|
|
076f82 |
+ dynlink probes tunables)
|
|
|
076f82 |
appendices = lang.texi header.texi install.texi maint.texi platform.texi \
|
|
|
076f82 |
contrib.texi
|
|
|
076f82 |
licenses = freemanuals.texi lgpl-2.1.texi fdl-1.3.texi
|
|
|
076f82 |
diff --git a/manual/dynlink.texi b/manual/dynlink.texi
|
|
|
076f82 |
new file mode 100644
|
|
|
076f82 |
index 0000000000000000..dbf3de11769d8e57
|
|
|
076f82 |
--- /dev/null
|
|
|
076f82 |
+++ b/manual/dynlink.texi
|
|
|
076f82 |
@@ -0,0 +1,100 @@
|
|
|
076f82 |
+@node Dynamic Linker
|
|
|
076f82 |
+@c @node Dynamic Linker, Internal Probes, Threads, Top
|
|
|
076f82 |
+@c %MENU% Loading programs and shared objects.
|
|
|
076f82 |
+@chapter Dynamic Linker
|
|
|
076f82 |
+@cindex dynamic linker
|
|
|
076f82 |
+@cindex dynamic loader
|
|
|
076f82 |
+
|
|
|
076f82 |
+The @dfn{dynamic linker} is responsible for loading dynamically linked
|
|
|
076f82 |
+programs and their dependencies (in the form of shared objects). The
|
|
|
076f82 |
+dynamic linker in @theglibc{} also supports loading shared objects (such
|
|
|
076f82 |
+as plugins) later at run time.
|
|
|
076f82 |
+
|
|
|
076f82 |
+Dynamic linkers are sometimes called @dfn{dynamic loaders}.
|
|
|
076f82 |
+
|
|
|
076f82 |
+@menu
|
|
|
076f82 |
+* Dynamic Linker Introspection:: Interfaces for querying mapping information.
|
|
|
076f82 |
+@end menu
|
|
|
076f82 |
+
|
|
|
076f82 |
+@node Dynamic Linker Introspection
|
|
|
076f82 |
+@section Dynamic Linker Introspection
|
|
|
076f82 |
+
|
|
|
076f82 |
+@Theglibc{} provides various functions for querying information from the
|
|
|
076f82 |
+dynamic linker.
|
|
|
076f82 |
+
|
|
|
076f82 |
+@deftypefun {int} dlinfo (void *@var{handle}, int @var{request}, void *@var{arg})
|
|
|
076f82 |
+@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
|
|
|
076f82 |
+@standards{GNU, dlfcn.h}
|
|
|
076f82 |
+This function returns information about @var{handle} in the memory
|
|
|
076f82 |
+location @var{arg}, based on @var{request}. The @var{handle} argument
|
|
|
076f82 |
+must be a pointer returned by @code{dlopen} or @code{dlmopen}; it must
|
|
|
076f82 |
+not have been closed by @code{dlclose}.
|
|
|
076f82 |
+
|
|
|
076f82 |
+On success, @code{dlinfo} returns 0. If there is an error, the function
|
|
|
076f82 |
+returns @math{-1}, and @code{dlerror} can be used to obtain a
|
|
|
076f82 |
+corresponding error message.
|
|
|
076f82 |
+
|
|
|
076f82 |
+The following operations are defined for use with @var{request}:
|
|
|
076f82 |
+
|
|
|
076f82 |
+@vtable @code
|
|
|
076f82 |
+@item RTLD_DI_LINKMAP
|
|
|
076f82 |
+The corresponding @code{struct link_map} pointer for @var{handle} is
|
|
|
076f82 |
+written to @code{*@var{arg}}. The @var{arg} argument must be the
|
|
|
076f82 |
+address of an object of type @code{struct link_map *}.
|
|
|
076f82 |
+
|
|
|
076f82 |
+@item RTLD_DI_LMID
|
|
|
076f82 |
+The namespace identifier of @var{handle} is written to
|
|
|
076f82 |
+@code{*@var{arg}}. The @var{arg} argument must be the address of an
|
|
|
076f82 |
+object of type @code{Lmid_t}.
|
|
|
076f82 |
+
|
|
|
076f82 |
+@item RTLD_DI_ORIGIN
|
|
|
076f82 |
+The value of the @code{$ORIGIN} dynamic string token for @var{handle} is
|
|
|
076f82 |
+written to the character array starting at @var{arg} as a
|
|
|
076f82 |
+null-terminated string.
|
|
|
076f82 |
+
|
|
|
076f82 |
+This request type should not be used because it is prone to buffer
|
|
|
076f82 |
+overflows.
|
|
|
076f82 |
+
|
|
|
076f82 |
+@item RTLD_DI_SERINFO
|
|
|
076f82 |
+@itemx RTLD_DI_SERINFOSIZE
|
|
|
076f82 |
+These requests can be used to obtain search path information for
|
|
|
076f82 |
+@var{handle}. For both requests, @var{arg} must point to a
|
|
|
076f82 |
+@code{Dl_serinfo} object. The @code{RTLD_DI_SERINFOSIZE} request must
|
|
|
076f82 |
+be made first; it updates the @code{dls_size} and @code{dls_cnt} members
|
|
|
076f82 |
+of the @code{Dl_serinfo} object. The caller should then allocate memory
|
|
|
076f82 |
+to store at least @code{dls_size} bytes and pass that buffer to a
|
|
|
076f82 |
+@code{RTLD_DI_SERINFO} request. This second request fills the
|
|
|
076f82 |
+@code{dls_serpath} array. The number of array elements was returned in
|
|
|
076f82 |
+the @code{dls_cnt} member in the initial @code{RTLD_DI_SERINFOSIZE}
|
|
|
076f82 |
+request. The caller is responsible for freeing the allocated buffer.
|
|
|
076f82 |
+
|
|
|
076f82 |
+This interface is prone to buffer overflows in multi-threaded processes
|
|
|
076f82 |
+because the required size can change between the
|
|
|
076f82 |
+@code{RTLD_DI_SERINFOSIZE} and @code{RTLD_DI_SERINFO} requests.
|
|
|
076f82 |
+
|
|
|
076f82 |
+@item RTLD_DI_TLS_DATA
|
|
|
076f82 |
+This request writes the address of the TLS block (in the current thread)
|
|
|
076f82 |
+for the shared object identified by @var{handle} to @code{*@var{arg}}.
|
|
|
076f82 |
+The argument @var{arg} must be the address of an object of type
|
|
|
076f82 |
+@code{void *}. A null pointer is written if the object does not have
|
|
|
076f82 |
+any associated TLS block.
|
|
|
076f82 |
+
|
|
|
076f82 |
+@item RTLD_DI_TLS_MODID
|
|
|
076f82 |
+This request writes the TLS module ID for the shared object @var{handle}
|
|
|
076f82 |
+to @code{*@var{arg}}. The argument @var{arg} must be the address of an
|
|
|
076f82 |
+object of type @code{size_t}. The module ID is zero if the object
|
|
|
076f82 |
+does not have an associated TLS block.
|
|
|
076f82 |
+@end vtable
|
|
|
076f82 |
+
|
|
|
076f82 |
+The @code{dlinfo} function is a GNU extension.
|
|
|
076f82 |
+@end deftypefun
|
|
|
076f82 |
+
|
|
|
076f82 |
+@c FIXME these are undocumented:
|
|
|
076f82 |
+@c dladdr
|
|
|
076f82 |
+@c dladdr1
|
|
|
076f82 |
+@c dlclose
|
|
|
076f82 |
+@c dlerror
|
|
|
076f82 |
+@c dlmopen
|
|
|
076f82 |
+@c dlopen
|
|
|
076f82 |
+@c dlsym
|
|
|
076f82 |
+@c dlvsym
|
|
|
076f82 |
diff --git a/manual/libdl.texi b/manual/libdl.texi
|
|
|
076f82 |
deleted file mode 100644
|
|
|
076f82 |
index e3fe0452d9f41d47..0000000000000000
|
|
|
076f82 |
--- a/manual/libdl.texi
|
|
|
076f82 |
+++ /dev/null
|
|
|
076f82 |
@@ -1,10 +0,0 @@
|
|
|
076f82 |
-@c FIXME these are undocumented:
|
|
|
076f82 |
-@c dladdr
|
|
|
076f82 |
-@c dladdr1
|
|
|
076f82 |
-@c dlclose
|
|
|
076f82 |
-@c dlerror
|
|
|
076f82 |
-@c dlinfo
|
|
|
076f82 |
-@c dlmopen
|
|
|
076f82 |
-@c dlopen
|
|
|
076f82 |
-@c dlsym
|
|
|
076f82 |
-@c dlvsym
|
|
|
076f82 |
diff --git a/manual/probes.texi b/manual/probes.texi
|
|
|
076f82 |
index 4aae76b81921f347..ee019e651706f492 100644
|
|
|
076f82 |
--- a/manual/probes.texi
|
|
|
076f82 |
+++ b/manual/probes.texi
|
|
|
076f82 |
@@ -1,5 +1,5 @@
|
|
|
076f82 |
@node Internal Probes
|
|
|
076f82 |
-@c @node Internal Probes, Tunables, Threads, Top
|
|
|
076f82 |
+@c @node Internal Probes, Tunables, Dynamic Linker, Top
|
|
|
076f82 |
@c %MENU% Probes to monitor libc internal behavior
|
|
|
076f82 |
@chapter Internal probes
|
|
|
076f82 |
|
|
|
076f82 |
diff --git a/manual/threads.texi b/manual/threads.texi
|
|
|
076f82 |
index 06b6b277a1228af1..7f166bfa87e88c36 100644
|
|
|
076f82 |
--- a/manual/threads.texi
|
|
|
076f82 |
+++ b/manual/threads.texi
|
|
|
076f82 |
@@ -1,5 +1,5 @@
|
|
|
076f82 |
@node Threads
|
|
|
076f82 |
-@c @node Threads, Internal Probes, Debugging Support, Top
|
|
|
076f82 |
+@c @node Threads, Dynamic Linker, Debugging Support, Top
|
|
|
076f82 |
@c %MENU% Functions, constants, and data types for working with threads
|
|
|
076f82 |
@chapter Threads
|
|
|
076f82 |
@cindex threads
|