From patchwork Mon May 20 13:35:12 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Nick Alcock X-Patchwork-Id: 90485 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 0296F385B50B for ; Mon, 20 May 2024 13:36:01 +0000 (GMT) X-Original-To: binutils@sourceware.org Delivered-To: binutils@sourceware.org Received: from mx0b-00069f02.pphosted.com (mx0b-00069f02.pphosted.com [205.220.177.32]) by sourceware.org (Postfix) with ESMTPS id E53ED385840F for ; Mon, 20 May 2024 13:35:24 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org E53ED385840F Authentication-Results: sourceware.org; dmarc=pass (p=quarantine dis=none) header.from=oracle.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=oracle.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org E53ED385840F Authentication-Results: server2.sourceware.org; arc=pass smtp.remote-ip=205.220.177.32 ARC-Seal: i=2; a=rsa-sha256; d=sourceware.org; s=key; t=1716212127; cv=pass; b=Oy8MGfe/3dqJ27DsI9tllCKZkF2B3bRAo/zoVQk31Hs18PJD43/XZjID5gFiCSUoxv3ceOK2KJ3ofe+2P/CQpBpZFQiFpulSXnnXGtqQtGZBTjMO2j+lqFHu1hPG2HvZNY8cx1ca0qhphHg1ogi9CtHHTi1MbWg9Qt0FWIauIEk= ARC-Message-Signature: i=2; a=rsa-sha256; d=sourceware.org; s=key; t=1716212127; c=relaxed/simple; bh=3H0GzX4YoCus9LbojWp6cBFViQZmY9h7hjcvlOSv4Kc=; h=DKIM-Signature:DKIM-Signature:From:To:Subject:Date:Message-ID: MIME-Version; b=LjT8SWYg4sJydJb60puszTEHbiXJC+EPpfRyXiBke1VBvzWA6AkaDJLJVnp8/Km4OmyNrRaL/dUQGcctMQXinK0Tb0xZKJJSKBea+p5VgGz/AAHefZwdd8aU8tNW07f/R4E0+dgFyOIOgFaKuAVTV7diaFpZ75r3fbhsElfAGKw= ARC-Authentication-Results: i=2; server2.sourceware.org Received: from pps.filterd (m0246631.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id 44KC9O1e007458 for ; Mon, 20 May 2024 13:35:24 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id : content-transfer-encoding : content-type : mime-version; s=corp-2023-11-20; bh=3BBU7KuU5hAdEYxVRQ5sjMwAlsZfHu+UBMt+JsRnQ7M=; b=CcKYtlukvAl+4L448bP56Iv7CjoPawtZCV3XA32vVX1plWZwUjOhPmztYOtTMZ7cpm2O yNz1ZpLUEO5tdyrvjGcSmo6luujEscuqEc/FGgaIr1Sw6ywwJN42uZnGl0S7hYUaQNI7 Mjy/V4Z91JkohsQSx4tt7Bqx0XwucPbBRzM3hoiFT4VsQ1I0/Kx/GjOK8fSWU22YE+tK pm+szdpTI3wufYsqhFv39fKXmSeD2czUxjRk1tIE4v5qHRPAPKjBtSIT7i9oTwoRGdN0 ruhLsHBNX3gtkJoAbah2zUqTje6ft2tEnPrU6Iyzio+TXAw7Kk3Xol/b20Mq77faj60Y /A== Received: from phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com (phxpaimrmta03.appoci.oracle.com [138.1.37.129]) by mx0b-00069f02.pphosted.com (PPS) with ESMTPS id 3y6k462pxw-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Mon, 20 May 2024 13:35:24 +0000 Received: from pps.filterd (phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com [127.0.0.1]) by phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com (8.17.1.19/8.17.1.19) with ESMTP id 44KCea2o005024 for ; Mon, 20 May 2024 13:35:23 GMT Received: from nam04-dm6-obe.outbound.protection.outlook.com (mail-dm6nam04lp2040.outbound.protection.outlook.com [104.47.73.40]) by phxpaimrmta03.imrmtpd1.prodappphxaev1.oraclevcn.com (PPS) with ESMTPS id 3y6js6d7ck-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Mon, 20 May 2024 13:35:23 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=IwTzVTksvYU+vzoz4W5XIY2lDm3zsIR5MwLpmmYJC243QcqXg4EFi54IC6vhKwWdG02f9BAdjnfWlhBLkxSxmD05+LlXIp1b5mJMw0Gmga5BpXUrwuPjUL3tM6hG2HzVYlcTJMnYiiLUNy/bHqkSvEfT4dAQAveTbGCHFsjnswLVwgwoXPTVhur+9tAZuid0gbXqvC6V7ce44WP/5vfPfQDeNKMPcgbGv41lSsX9U0pPG3rFXF2OBXlAUcVYP2W4tLPeT4LHwD4U4HOyqr4+h/rCBnIDqP1f+FA3l4JN0HVwGvzM7PlPfRqSEbWZ9W9kQ+dwiclDuJP5di4x6NNfmw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=3BBU7KuU5hAdEYxVRQ5sjMwAlsZfHu+UBMt+JsRnQ7M=; b=j3yvqxQ7JAFxwbjDTaZZPmM2dsPFRgwVKsg7aIkfhii1WYfyEFV/bmMPeHGxPgrmSMkU6SfPSs+glKcqJhRsNCxah8hfKwEowXAVeCPhrLJfXACoI47DbsAV5kYtNn3TdpfTizLlc12q9wYxzMkuCbkPyMdp2g4iPXu7nOT4zPNvLRXKmu4xAHnxVmOrXo2MyhAVOyq6xl3Wt65biqwTBY2ACOmUmEao6vZxVMFHVAyxbxZKgSvhnlzGR6rMNQ0zp6KYeAipcqrm6tuguRt2NNPzsZPSZ+K/s67g7ICnUWYXK3YKVNaAczEVXeo+nGpIDgz6TwvVTYroHqeGy8XalQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=3BBU7KuU5hAdEYxVRQ5sjMwAlsZfHu+UBMt+JsRnQ7M=; b=sI4wg50ojQwh0mNX73yduNB8Vu6exHPVZ0HvxtOY7yNzX4we0oiDWOb9pMOwF4cAcgGMLpFBY9QzkRBSl/SdMFxmahbCuVsIrnoNceklF4pqQSiG+BDAgmJtisM54rLztFjI0mXmahCozJFd/K6SdUCYMVC4NLV0vurj8WQ/938= Received: from MW4PR10MB6608.namprd10.prod.outlook.com (2603:10b6:303:22e::8) by PH0PR10MB4790.namprd10.prod.outlook.com (2603:10b6:510:3f::12) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7587.36; Mon, 20 May 2024 13:35:20 +0000 Received: from MW4PR10MB6608.namprd10.prod.outlook.com ([fe80::f9b2:8c8b:841a:aff3]) by MW4PR10MB6608.namprd10.prod.outlook.com ([fe80::f9b2:8c8b:841a:aff3%3]) with mapi id 15.20.7587.035; Mon, 20 May 2024 13:35:20 +0000 From: Nick Alcock To: binutils@sourceware.org Cc: stephen.brennan@oracle.com Subject: [PATCH] include, libctf: improve documentation Date: Mon, 20 May 2024 14:35:12 +0100 Message-ID: <20240520133512.133727-1-nick.alcock@oracle.com> X-Mailer: git-send-email 2.45.1.275.g567cb0950c X-ClientProxiedBy: LO4P265CA0244.GBRP265.PROD.OUTLOOK.COM (2603:10a6:600:350::10) To MW4PR10MB6608.namprd10.prod.outlook.com (2603:10b6:303:22e::8) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: MW4PR10MB6608:EE_|PH0PR10MB4790:EE_ X-MS-Office365-Filtering-Correlation-Id: 11107853-0ab7-4d7e-5d11-08dc78d1b1cc X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0;ARA:13230031|376005|1800799015|366007; X-Microsoft-Antispam-Message-Info: 61xBwoP4i6WvD+AkXcqM1yA+vXUW1SeZIo6EbOJX7zNm/FD+vnScS49kIrlpBuSPWxVfQz+ariOWhg6P85HmlPNjTMJp2fhQxKzR7UNmweddRBy6SbXd4g3zzlbZFUk0DtmLFRrVwNVtVIdvmPDQ67DTE4DnamUBpAD6/f1yI0nSG7PD60R0KuIrzLOi8u691P1iFv4u6fRP/wtnzB9hWQGEdDlhflqAszw0ZKuWWm6KqRe5dVjPwM18KvCb0eeOD3RkmDEtobFrf8QiiNCWeF2ZhoTeilve5kP35WIkECM8mrUIfV2pp/VXazxWlKIETo0IOChEWFerePbQ17gEFfrD3d36jnIZeI7Lp50P3c9dsVMiPoHoYBRlKhW0lR/o5yccqrT5F4ykC/ihim5VxzKhOFvmRDkMbyVeGw4c+GFsTjZitO1TlMB81RjJjoij6I7FpPKzB6sUqLStP9vm18eKVPDF4ergdeoisrtWN5tR9ZkhtURKanFBHslbodcBTCdqoZmNh3kyTercfTxG1x2DDdqPxqKFLodFRFsyPf7OMmO11Zv5yOMlKdl3INpmiKqpCtkGXp+/UMcJ5rzzn6njwLq0Jw/Aly/R5+/3SPPumbvtonYLK8yqPYssY3jtsSOBHJwVXTUex6RLbmgE9kU0LAlfg6ycaBbQWOR6ZWStSO+xmrAi00vFM+GKd3VbGfFDtyYDBBdwQhpbWSB+OHJ1YuEYRdXLwGDsUVVHx04Y36zlCq1Nay17X6QuiW0ZRzlhfq/43NYKeQEX0hCFlSLmonnofY+rQ8o0LjHcCdtzO2FZuvhKhJWszTyaY93z7rS4WkNdYfZjhPsdgePq1Uelf05nZK/UkCQ58aqMkNrTYk14EkL6Yde4ITUEHcKP/hpESjC1PWvibNk4mTOGZyUa7jR5Q1h+tRRYvMN4VWBKSIK7fEWVorAlMXOOcCpb6NrX5sTmmogIMKp0NSY0dsd6KyznEOTYr98fycfOlCzJxXAhI+eSJrD0sZ94q9uWgDTcMu1ooOF2fbxu1XgGrNqH3iqSBFlhytY0iFdvgjQ55dCtzlTL0uDfBazdcYsiHIq0uW9UiyZl8cDRCX2Luz63bhGoR4cv7fnVIQmzso0xrValKjWgmrca+1cUk9i/OOk4fiUCIB4CGAOT0jPSzoIEEn30KzQEYxWv3BILEU9hi5gOGI057R2m6F3RAgl0k3UpRRwSlTqEg1XjiH/8NXDDvn4CmGtjRKpdMy+CGnSCMFVoDwFR8EgevXS6tNrCrwg8Nnc36/l/Z2ap49gjqw== X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:MW4PR10MB6608.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230031)(376005)(1800799015)(366007); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: b3KRu4RNfjgNI0Dnyo4qSmKUa4gsCVRr/GB53xpnJ2apBpDUXvgarXHl4DEhbzKKQTtCBjF7fcVhjC+YF1JH9s/+WMn4/1XrXNaUknli03UrwQrbbZPimICK0LMeBJQe68AGZjZjZvDqDZ1h7f+B7uHFeS6laS5T8DGB+1OnW69FgsqUOHyS5+x3zsMKFONf1zp5+SNS6DKOieLcPRS73CYDXF7HccOvojiYnqGm1uSJQ4pFISOfXpA312VncXzHUIpaQaLIE2uJW3AxXBxe4Fo73EmOZ/PGbQtD/I1OwiHLQA2UU1yTMdmwKI0knJ2b2z151jlZd9uOCYx/djflQBvdOffP04NuHZQGYrgCspmc9RtfB8uIeBxWTAqIWHa3aFfkZ0qVaaQe/YggpKnqOsFGXymK2hHN1UvtQyRz2FonaiziLOfGGO/v+ixvhcOuaV/sPiKQ0sfebMYqAzu+D7fiuGo3RzK+F2zdtovKKRrWQk3m0P9uJeGiTNmkRn2U45OSMq6KK/HqhFPPaW9Eo7d6AMqitEt0LaOob/LpZzL4J/tgnXIUV3CvdpxIJ64cqETx05MwF+vB+blQHmla0rou5OvDv9OPFupsBUiHRUbycgsSCefn7qoLEAm1AkQsPxTQ5wBCV+2aBsLG497gP6kM+LI+cjv74kXiHqgfVHI41jEd7BrssT9Vvwrc/vTzLKt3e2HJ7I7YCqFFJq5qY8+BGViWNfpzu5AREuYDhE5YPJli+ToVSF77S4CUaQ3/hgFp+oAooKjLB5w8sTgP/NwPOIILYD13OsOgwKpudQsXDgIF920+qFZH1zByzzb4uti6uhlgvwWQ9KqjSKqr3hc7zNKxO+F95tr3zSIA8gUfPm+GVgqh0fhQMI7kUW61Wgpk18gr+fsLTpF507l3TUTzGXpVdlufMiH5hiPNnU61LvtXcTdyg0u0UV9D5vCMRoC3n+A16+pzTnX74jmOlVS9D7MlquOzGn8cGSQE/H+4LlXorOuLGOlxHmkum6A7CiW5F/BP1Sga8Aax7iyzvOxtwpRiorM+vNzO9YIelI/rm7y/ZVES0FN0vmVUiKPs3yOLm46KL4+T0zioIX3sYIijDHtytXpkLYU7hfiBW23JYo3e4ixGDuNKOdqWn9lmNR1vLYTaTpFkaBFH0wIccu4gRFXej8rV+EF/LUaLU3XdpI3mzoMk4fbFrkWJhXX5teqoMJxcakBwwf9yXGTzdHDA/nWXT/DEKRr1vFeVR3RYhqodGM4sH9YFRtJx948kOaN2Pwr8fomuz8XWQcZlaRgygxAY0gocn8mvCos4GQFDRoXgeV4KWCZG1kC27o3lXBWF2z/fDH2XlNix/cJwdBCLTN/490USj6zA4rcN5uzk+hcZDebR2eV3hELTbfSaUvMa7TRBNIH2Zz6hP4Gj7QzLaXEwVeIBv9fZPtb7Ybs9clKqKPywV2Mkt9SoOIsF1oXzaX393ljxFuu7EEqIhQiRetLNoF/APnoBLQ2+ygLoaMS4mc4tYqtrXlV2/Hpots/+GKAFDzONCi43KE4+ITy60iEuDrhYxbA+0iewBWavsw6IilQRoX+sWVieVIP0nhRVjscbP+PkZS8iKjMGNQ== X-MS-Exchange-AntiSpam-ExternalHop-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-ExternalHop-MessageData-0: wxtSEK+rAopTuXKE6n2XA2UdE6YmYER6Q9cX+A7wQ/LDqvbG3gSAsFtSDil5NUmCiEmj8gQy3h9u1m8ZTOj5hrYvcz89VHtxdk7NOBqMUITT14YJyxDWGd2MVsYDu4JvphRd7PRNwkkifdLgqZb0mtLILiVxRdvJA4VBXyiBU+6zngHmacJFGZtmD9b453HUnAZRvTFXK1GC2drrgCb/dJceflkdwn2GTL+UDb8ckrUILgqkr+bqoAW/q291UaFr2tl/urc2mILLXAZPdwEFvEVmqDHcDq60kbG3yTcrtI2AnWFYCz3p9w4/exbkbwuCuescGhVZ/1KUNj1YtTnZWYBr2YPrM/lqa+hWMK8YnpuLbMLZq4KiYcwOzRm7uHBMNwbzwmW/UYcA+pGcye0nz9gtoG+e9PkAEAlbnQPq7nnma6fqFEPO0OEzTSg52I5QUqhApTJdkprBl+93U2dwaEe/tVCX9veY5pfS5cquG/epwxGatNDGVF/fap4JMJtnWdzP4AB0eU3Q90xy28N7kcLyL3UZWlNa8lyPn8chrEMGQVmFWE1g8nkzYHSLHkk/QQr266z/SVbVy6lT42Fp6g8INDDFHyLd6+GFcUlpO7A= X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-Network-Message-Id: 11107853-0ab7-4d7e-5d11-08dc78d1b1cc X-MS-Exchange-CrossTenant-AuthSource: MW4PR10MB6608.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 20 May 2024 13:35:20.8323 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: 0eUQRyos0JixXFi/4Jx0l4LrV0IKE6mf951ctFQX/AmhA8dTZAvcqR0zD6Z4uJjc6ZjeP0pDQFsCtlQvXgSlTg== X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH0PR10MB4790 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1039,Hydra:6.0.650,FMLib:17.12.28.16 definitions=2024-05-20_05,2024-05-17_03,2024-05-17_01 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 malwarescore=0 phishscore=0 suspectscore=0 mlxscore=0 adultscore=0 mlxlogscore=999 spamscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2405010000 definitions=main-2405200111 X-Proofpoint-ORIG-GUID: u6zQq454j8DjI-trD7JwNUnBMCiMwF5G X-Proofpoint-GUID: u6zQq454j8DjI-trD7JwNUnBMCiMwF5G X-Spam-Status: No, score=-12.3 required=5.0 tests=BAYES_00, 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 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: binutils@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Binutils mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: binutils-bounces+patchwork=sourceware.org@sourceware.org Some review comments came in after I pushed the last lot of ctf-api.h comment improvements. They were good, so I've incorporated them. Mostly: better _next iterator usage info, better info on ctf_*open functions, and better info on ctf_type_aname and ctf_type_name_raw. include/ * ctf-api.h: improve documentation. --- include/ctf-api.h | 94 +++++++++++++++++++++++++++++++---------------- 1 file changed, 62 insertions(+), 32 deletions(-) diff --git a/include/ctf-api.h b/include/ctf-api.h index 0d7f584e5d7..392964a4ac9 100644 --- a/include/ctf-api.h +++ b/include/ctf-api.h @@ -303,7 +303,26 @@ typedef struct ctf_dump_state ctf_dump_state_t; /* Iteration state for the _next functions, and allocators/copiers/freers for it. (None of these are needed for the simple case of iterating to the end: - the _next function allocate and free the iterators for you.) */ + the _next functions allocate and free the iterators for you.) + + The _next iterators all work in similar ways: they take things to query (a + dict, a name, a type ID, something like that), then a ctf_next_t iterator + arg which must be the address of a variable whose value is NULL on first + call, and will be set to NULL again once iteration has completed. + + They return something important about the thing being iterated over (often a + type ID or a name); on end of iteration they instead return return CTF_ERR, + -1, or NULL and set the error ECTF_NEXT_END on the dict. They can often + provide more information too: this is done via pointer parameters (e.g. the + membname and membtype in ctf_member_next()). These parameters are always + optional and can be set to NULL if not needed. + + Errors other than end-of-iteration will return CTF_ERR/-1/NULL and set the + error to something other than ECTF_NEXT_END, and *not* destroy the iterator: + you should either recover somehow and continue iterating, or call + ctf_next_destroy() on it. (You can call ctf_next_destroy() on a NULL + iterator, so it's safe to just unconditionally do it after iteration has + completed.) */ typedef struct ctf_next ctf_next_t; extern ctf_next_t *ctf_next_create (void); @@ -314,11 +333,10 @@ extern ctf_next_t *ctf_next_copy (ctf_next_t *); archives: so they can be used to open both. CTF files will appear to be an archive with one member named '.ctf'. - Some of these functions take raw symtab and strtab section content in the - form of ctf_sect_t structures. For CTF in ELF files, these should be - extracted from .dynsym and its associated string table (usually .dynsym) - whenever the CTF_F_DYNSTR flag is set in the CTF preamble (which it almost - always will be for linked objects, but not for .o files). */ + All these functions except for ctf_close use BFD and can open anything BFD + can open, hunting down the .ctf section for you, so are not available in the + libctf-nobfd flavour of the library. If you want to provide the CTF section + yourself, you can do that with ctf_bfdopen_ctfsect. */ extern ctf_archive_t *ctf_bfdopen (struct bfd *, int *); extern ctf_archive_t *ctf_bfdopen_ctfsect (struct bfd *, const ctf_sect_t *, @@ -334,8 +352,8 @@ extern ctf_sect_t ctf_getdatasect (const ctf_dict_t *); extern ctf_sect_t ctf_getsymsect (const ctf_dict_t *); extern ctf_sect_t ctf_getstrsect (const ctf_dict_t *); -/* Symbol sections have an endianness which may be different from the - endianness of the CTF dict. Called for you by ctf_open and ctf_fdopen, +/* Set the endianness of the symbol section, which may be different from + the endianness of the CTF dict. Done for you by ctf_open and ctf_fdopen, but direct calls to ctf_bufopen etc with symbol sections provided must do so explicitly. */ @@ -347,12 +365,23 @@ extern void ctf_arc_symsect_endianness (ctf_archive_t *, int little_endian); done until all dicts are finished with and closed themselves. Almost all functions that open archives will also open raw CTF dicts, which - are treated as if they were archives with only one member. */ + are treated as if they were archives with only one member. + + Some of these functions take optional raw symtab and strtab section content + in the form of ctf_sect_t structures. For CTF in ELF files, the more + convenient opening functions above extract these .dynsym and its associated + string table (usually .dynsym) whenever the CTF_F_DYNSTR flag is set in the + CTF preamble (which it almost always will be for linked objects, but not for + .o files). If you use ctf_arc_bufopen and do not specify symbol/string + tables, the ctf_*_lookuup_symbol functions will fail with ECTF_NOSYMTAB. + + Like many other convenient opening functions, ctf_arc_open needs BFD and is + not available in libctf-nobfd. */ extern ctf_archive_t *ctf_arc_open (const char *, int *); -extern ctf_archive_t *ctf_arc_bufopen (const ctf_sect_t *, - const ctf_sect_t *, - const ctf_sect_t *, +extern ctf_archive_t *ctf_arc_bufopen (const ctf_sect_t *ctfsect, + const ctf_sect_t *symsect, + const ctf_sect_t *strsect, int *); extern void ctf_arc_close (ctf_archive_t *); @@ -378,8 +407,8 @@ extern size_t ctf_archive_count (const ctf_archive_t *); extern ctf_dict_t *ctf_dict_open (const ctf_archive_t *, const char *, int *); extern ctf_dict_t *ctf_dict_open_sections (const ctf_archive_t *, - const ctf_sect_t *, - const ctf_sect_t *, + const ctf_sect_t *symsect, + const ctf_sect_t *strsect, const char *, int *); /* Look up symbols' types in archives by index or name, returning the dict @@ -400,10 +429,14 @@ extern void ctf_arc_flush_caches (ctf_archive_t *); ctf_dict_open_sections, they can be passed symbol and string table sections. */ -extern ctf_dict_t *ctf_simple_open (const char *, size_t, const char *, size_t, - size_t, const char *, size_t, int *); -extern ctf_dict_t *ctf_bufopen (const ctf_sect_t *, const ctf_sect_t *, - const ctf_sect_t *, int *); +extern ctf_dict_t *ctf_simple_open (const char *ctfsect, size_t ctfsect_size, + const char *symsect, size_t symsect_size, + size_t symsect_entsize, + const char *strsect, size_t strsect_size, + int *errp); +extern ctf_dict_t *ctf_bufopen (const ctf_sect_t *ctfsect, + const ctf_sect_t *symsect, + const ctf_sect_t *strsect, int *); extern void ctf_ref (ctf_dict_t *); extern void ctf_dict_close (ctf_dict_t *); @@ -484,14 +517,7 @@ extern ctf_id_t ctf_lookup_by_symbol (ctf_dict_t *, unsigned long); extern ctf_id_t ctf_lookup_by_symbol_name (ctf_dict_t *, const char *); /* Traverse all (function or data) symbols in a dict, one by one, and return the - type of each and (if NAME is non-NULL) optionally its name. - - This is the first of a family of _next iterators that all work in similar - ways: the ctf_next_t iterator arg must be the address of a variable whose - value is NULL on first call, and will be set to NULL again once iteration has - completed (which also returns CTF_ERR as the type and sets the error - ECTF_NEXT_END on the dict). If you want to exit earlier, call - ctf_next_destroy on the iterator. */ + type of each and (if NAME is non-NULL) optionally its name. */ extern ctf_id_t ctf_symbol_next (ctf_dict_t *, ctf_next_t **, const char **name, int functions); @@ -525,8 +551,9 @@ extern ctf_id_t ctf_lookup_variable (ctf_dict_t *, const char *); extern ctf_id_t ctf_type_resolve (ctf_dict_t *, ctf_id_t); -/* Get the name of a type, including any cvr-quals, and return it as a new - dynamically-allocated string. */ +/* Get the name of a type, including any const/volatile/restrict qualifiers + (cvr-quals), and return it as a new dynamically-allocated string. + (The 'a' stands for 'a'llocated.) */ extern char *ctf_type_aname (ctf_dict_t *, ctf_id_t); @@ -534,6 +561,9 @@ extern char *ctf_type_aname (ctf_dict_t *, ctf_id_t); extern char *ctf_type_aname_raw (ctf_dict_t *, ctf_id_t); +/* A raw name that is owned by the ctf_dict_t and will live as long as it + does. Do not change the value this function returns! */ + extern const char *ctf_type_name_raw (ctf_dict_t *, ctf_id_t); /* Like ctf_type_aname, but print the string into the passed buffer, truncating @@ -915,10 +945,10 @@ extern void ctf_file_close (ctf_file_t *); extern ctf_dict_t *ctf_parent_file (ctf_dict_t *); extern ctf_dict_t *ctf_arc_open_by_name (const ctf_archive_t *, const char *, int *); -extern ctf_dict_t *ctf_arc_open_by_name_sections (const ctf_archive_t *, - const ctf_sect_t *, - const ctf_sect_t *, - const char *, int *); +extern ctf_dict_t *ctf_arc_open_by_name_sections (const ctf_archive_t *arc, + const ctf_sect_t *symsect, + const ctf_sect_t *strsect, + const char *name, int *errp); /* Deprecated witeout function to write out a gzip-compressed dict. Unlike all the other writeout functions, this even compresses the header (it has to,