From patchwork Fri Feb 16 13:34:18 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mark Wielaard X-Patchwork-Id: 85881 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 2B9C23858010 for ; Fri, 16 Feb 2024 13:34:53 +0000 (GMT) X-Original-To: elfutils-devel@sourceware.org Delivered-To: elfutils-devel@sourceware.org Received: from gnu.wildebeest.org (gnu.wildebeest.org [45.83.234.184]) by sourceware.org (Postfix) with ESMTPS id CE960385829E for ; Fri, 16 Feb 2024 13:34:35 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org CE960385829E Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=klomp.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=klomp.org ARC-Filter: OpenARC Filter v1.0.0 sourceware.org CE960385829E Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=45.83.234.184 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1708090484; cv=none; b=Z7CQ1TH+FxrX20VUjkA6p4xB0JJmGeeJC7O+dqZL0RHRjQjAVfE/JBUXk1qcZKf8o3DhvX7ECXv+JIJBJlnsQSKjSxbvCK/s9bV4kXgfF1qQPqEqX3jTcvnZo5/IwqVwPwLiU3aUqrUegZkHJMg74kqbLAh77J3jMT48PTUMIWA= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1708090484; c=relaxed/simple; bh=p2Krz2rgrRqjIDAzhUrYwVlbmaexRHRmhCXn75XPl6g=; h=From:To:Subject:Date:Message-ID:MIME-Version; b=Oo0NLo3VqPfy1h1YTNnjU2USbY7AqxrynAtI+To/TsbUg4b1DwTZp5w75rD0aJBcy30Y61K0XuKpEH5cMboB+z/qGKgAw6Mb+QAJ/+amyhEbRmRbgoRJws22x/5zfWYNk2b6PKPRutNYzhqcTdMuPxtUT5v8RtR2zUbOIbF+69M= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from r6.localdomain (82-217-174-174.cable.dynamic.v4.ziggo.nl [82.217.174.174]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by gnu.wildebeest.org (Postfix) with ESMTPSA id B5EF830005AA; Fri, 16 Feb 2024 14:34:34 +0100 (CET) Received: by r6.localdomain (Postfix, from userid 1000) id 77A63340518; Fri, 16 Feb 2024 14:34:34 +0100 (CET) From: Mark Wielaard To: elfutils-devel@sourceware.org Cc: Omar Sandoval , Mark Wielaard Subject: [PATCH] libdw: Update dwarf_cu_dwp_section_info documentation Date: Fri, 16 Feb 2024 14:34:18 +0100 Message-ID: <20240216133419.79608-1-mark@klomp.org> X-Mailer: git-send-email 2.43.2 MIME-Version: 1.0 X-Spam-Status: No, score=-8.2 required=5.0 tests=BAYES_00, GIT_PATCH_0, JMQ_SPF_NEUTRAL, KAM_DMARC_STATUS, RCVD_IN_BARRACUDACENTRAL, SPF_HELO_NONE, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: elfutils-devel@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Elfutils-devel mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: elfutils-devel-bounces+patchwork=sourceware.org@sourceware.org Update the documentation of dwarf_cu_dwp_section_info to make clear that the function only returns an error if the DWARF package file data couldn't be read or an unknown section constant is provided. Missing DWP information for a given CU isn't an error and will set both OFFSET and SIZE to zero. It also makes sure the documentation is < 76 chars wide. * libdw/libdw.h (dwarf_cu_dwp_section_info): Update docs. Signed-off-by: Mark Wielaard --- libdw/libdw.h | 42 +++++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/libdw/libdw.h b/libdw/libdw.h index 545ad043..d53dc787 100644 --- a/libdw/libdw.h +++ b/libdw/libdw.h @@ -1081,25 +1081,29 @@ extern int dwarf_frame_register (Dwarf_Frame *frame, int regno, __nonnull_attribute__ (3, 4, 5); -/* Return offset and/or size of CU's contribution to SECTION in a DWARF package - file. - - If CU is not from a DWARF package file, the file does not have SECTION, or CU - does not contribute to SECTION, then *SIZEP is set to 0. - - SECTION is a DW_SECT section identifier. Note that the original GNU DWARF - package file extension for DWARF 4 used slightly different section - identifiers. This function uses the standardized section identifiers and - maps the GNU DWARF 4 identifiers to their standard DWARF 5 analogues: - DW_SECT_LOCLISTS (5) refers to .debug_locs.dwo for DWARF 4. - DW_SECT_MACRO (7) refers to .debug_macinfo.dwo for DWARF 4 or - .debug_macro.dwo for the GNU .debug_macro extension for DWARF 4 (section - identifier 8 is DW_SECT_RNGLISTS in DWARF 5, NOT DW_SECT_MACRO like in the - GNU extension.) - .debug_types.dwo does not have a DWARF 5 equivalent, so this function accepts - the original DW_SECT_TYPES (2). - - Returns 0 for success or -1 for errors. OFFSETP and SIZEP may be NULL. */ +/* Return offset and/or size of CU's contribution to SECTION in a + DWARF package file. + + If CU is not from a DWARF package file, the file does not have + SECTION, or CU does not contribute to SECTION, then *OFFSETP and + *SIZEP are set to 0 (this is not an error and the function will + return 0 in that case). + + SECTION is a DW_SECT section identifier. Note that the original + GNU DWARF package file extension for DWARF 4 used slightly + different section identifiers. This function uses the standardized + section identifiers and maps the GNU DWARF 4 identifiers to their + standard DWARF 5 analogues: DW_SECT_LOCLISTS (5) refers to + .debug_locs.dwo for DWARF 4. DW_SECT_MACRO (7) refers to + .debug_macinfo.dwo for DWARF 4 or .debug_macro.dwo for the GNU + .debug_macro extension for DWARF 4 (section identifier 8 is + DW_SECT_RNGLISTS in DWARF 5, NOT DW_SECT_MACRO like in the GNU + extension.) .debug_types.dwo does not have a DWARF 5 equivalent, + so this function accepts the original DW_SECT_TYPES (2). + + Returns 0 for success or -1 for errors reading the DWARF package + file data or if an unknown SECTION constant is given. OFFSETP and + SIZEP may be NULL. */ extern int dwarf_cu_dwp_section_info (Dwarf_CU *cu, unsigned int section, Dwarf_Off *offsetp, Dwarf_Off *sizep);