[PATCH] manual: Document the dlinfo function

[PATCH] manual: Document the dlinfo function

[Florian Weimer]

---
 manual/dynlink.texi | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

diff --git a/manual/dynlink.texi b/manual/dynlink.texi
index 54091be18e..7cc65c3ad5 100644
--- a/manual/dynlink.texi
+++ b/manual/dynlink.texi
@@ -22,6 +22,72 @@ Dynamic linkers are sometimes called @dfn{dynamic loaders}.
 @Theglibc{} provides various functions for querying information from the
 dynamic linker.
 
+@deftypefun {int} dlinfo (void *@var{handle}, int @var{request}, void *@var{arg})
+This function returns information about @var{handle} in the memory
+location @var{arg}, based on @var{request}.  The @var{handle} argument
+must be a pointer returned by @code{dlopen} or @code{dlmopen}; it must
+not have been closed by @code{dlclose}.
+
+On success, @code{dlinfo} returns 0.  If there is an error, the function
+returns @math{-1}, and @code{dlerror} can be used to obtain a
+corresponding error message.
+
+The following operations are defined for use with @var{request}:
+
+@vtable @code
+@item RTLD_DI_LINKMAP
+The corresponding @code{struct link_map} pointer for @var{handle} is
+written to @code{*@var{arg}}.  The @var{arg} argument must be the
+address of an object of type @code{struct link_map *}.
+
+@item RTLD_DI_LMID
+The namespace identifier of @var{handle} is written to
+@code{*@var{arg}}.  The @var{arg} argument must be the address of an
+object of type @code{Lmid_t}.
+
+@item RTLD_DI_ORIGIN
+The value of the @code{$ORIGIN} dynamic string token for @var{handle} is
+written to the character array starting at @var{arg} as a
+null-terminated string.
+
+This request type should not be used because it is prone to buffer
+overflows.
+
+@item RTLD_DI_SERINFO
+@item RTLD_DI_SERINFOSIZE
+These requests can be used to obtain search path information for
+@var{handle}.  For both requests, @var{arg} must point to a
+@code{Dl_serinfo} object.  The @code{RTLD_DI_SERINFOSIZE} request must
+be made first; it updates the @code{@var{arg}->dls_size} and
+@code{@var{arg}->dls_cnt} members.  The caller should then allocate
+memory to store at least @code{dls_size} bytes and pass that buffer to a
+@code{RTLD_DI_SERINFO} request.  This second request fills the
+@code{dls_serpath} array.  The number of array elements was returned in
+the @code{dls_cnt} member in the initial @code{RTLD_DI_SERINFOSIZE} request.
+The caller is responsible for freeing the allocated buffer.
+
+This interface is prone to buffer overflows in multi-threaded because
+the size can change between the @code{RTLD_DI_SERINFOSIZE} and
+@code{RTLD_DI_SERINFO} requests.
+
+@item RTLD_DI_TLS_DATA
+This request writes the address of the TLS block (in the current thread)
+for the shared object identified by @var{handle} to a @code{void *}
+object at address @var{arg} (that is, @var{arg} must be of type
+@code{void **}).  A null pointer is written if the object does not have
+any associated TLS block.
+
+@item RTLD_DI_TLS_MODID
+This request writes the TLS module ID for the shared object @var{handle}
+to @code{*@var{arg}}.  The argument @var{arg} must be a pointer to an
+object of type @code{size_t}.  The module ID is zero if the object
+does not have an associated TLS block.
+@end vtable
+@end deftypefun
+
+The reminder of this section documents the @code{_dl_find_object}
+function and supporting types and constants.
+
 @deftp {Data Type} {struct dl_find_object}
 @standards{GNU, dlfcn.h}
 This structure contains information about a main program or loaded
@@ -130,7 +196,6 @@ This function is a GNU extension.
 @c dladdr1
 @c dlclose
 @c dlerror
-@c dlinfo
 @c dlmopen
 @c dlopen
 @c dlsym

Re: [PATCH] manual: Document the dlinfo function

[Andreas Schwab]

On Apr 14 2022, Florian Weimer via Libc-alpha wrote:

> +@item RTLD_DI_SERINFO
> +@item RTLD_DI_SERINFOSIZE

The second @item needs to be @itemx.

> +These requests can be used to obtain search path information for
> +@var{handle}.  For both requests, @var{arg} must point to a
> +@code{Dl_serinfo} object.  The @code{RTLD_DI_SERINFOSIZE} request must
> +be made first; it updates the @code{@var{arg}->dls_size} and
> +@code{@var{arg}->dls_cnt} members.

This is misleading since arg is a void pointer.  Perhaps just refer to
the members by their name:

  ... it updates the @code{dls_size} and @code{dls_cnt} members of the
  @code{Dl_serinfo} object.

> +This interface is prone to buffer overflows in multi-threaded because

+processes

> +@item RTLD_DI_TLS_DATA
> +This request writes the address of the TLS block (in the current thread)
> +for the shared object identified by @var{handle} to a @code{void *}
> +object at address @var{arg} (that is, @var{arg} must be of type
> +@code{void **}).

This description is weirdly different from the others wrt. how @var{arg}
is described.  I think how the other places describe it is better.

> +The reminder of this section documents the @code{_dl_find_object}

remainder

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."