From patchwork Thu Apr 14 15:02:58 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 1617299 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.ozlabs.org; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.a=rsa-sha256 header.s=default header.b=MLGq1e0s; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=sourceware.org (client-ip=2620:52:3:1:0:246e:9693:128c; helo=sourceware.org; envelope-from=libc-alpha-bounces+incoming=patchwork.ozlabs.org@sourceware.org; receiver=) Received: from sourceware.org (server2.sourceware.org [IPv6:2620:52:3:1:0:246e:9693:128c]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4KfN4p1rnXz9sG4 for ; Fri, 15 Apr 2022 01:03:22 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id C68683857370 for ; Thu, 14 Apr 2022 15:03:19 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org C68683857370 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1649948599; bh=nbJmN0WWdqOZuqqDKujw1hIsGNfkiatktp6i8Y4kRSg=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:From; b=MLGq1e0sIZDXZgLeeC2uTRJhLBfT/wthCPMM/yJf0GPtJxowU8zGriEUDa/dY/1aK MCOxZzoeeB5r5Zak/ntMSUDm2wfG1qUb2h0FlbFtZnK08TBmSf3Xvxt+J4f17c4X0r tWLlDXG+ldqPymoyEgmhqBGLT/fr9a5Wxf2QMqm8= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id 6486D3857C4A for ; Thu, 14 Apr 2022 15:03:03 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 6486D3857C4A Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-29-cbHN-ipROpGdm7mg6gWwVg-1; Thu, 14 Apr 2022 11:03:01 -0400 X-MC-Unique: cbHN-ipROpGdm7mg6gWwVg-1 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 7DDA786B8A4 for ; Thu, 14 Apr 2022 15:03:01 +0000 (UTC) Received: from oldenburg.str.redhat.com (unknown [10.39.193.61]) by smtp.corp.redhat.com (Postfix) with ESMTPS id D6EAA53CD for ; Thu, 14 Apr 2022 15:03:00 +0000 (UTC) To: libc-alpha@sourceware.org Subject: [PATCH] manual: Document the dlinfo function Date: Thu, 14 Apr 2022 17:02:58 +0200 Message-ID: <87zgknwvvh.fsf@oldenburg.str.redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.11.54.5 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-10.8 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Florian Weimer via Libc-alpha From: Florian Weimer Reply-To: Florian Weimer Errors-To: libc-alpha-bounces+incoming=patchwork.ozlabs.org@sourceware.org Sender: "Libc-alpha" --- 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