1.\" $NetBSD: elf_getarsym.3,v 1.6 2024/03/03 17:37:33 christos Exp $ 2.\" 3.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" This software is provided by Joseph Koshy ``as is'' and 15.\" any express or implied warranties, including, but not limited to, the 16.\" implied warranties of merchantability and fitness for a particular purpose 17.\" are disclaimed. in no event shall Joseph Koshy be liable 18.\" for any direct, indirect, incidental, special, exemplary, or consequential 19.\" damages (including, but not limited to, procurement of substitute goods 20.\" or services; loss of use, data, or profits; or business interruption) 21.\" however caused and on any theory of liability, whether in contract, strict 22.\" liability, or tort (including negligence or otherwise) arising in any way 23.\" out of the use of this software, even if advised of the possibility of 24.\" such damage. 25.\" 26.\" Id: elf_getarsym.3 3955 2022-03-12 12:24:36Z jkoshy 27.\" 28.Dd August 15, 2006 29.Dt ELF_GETARSYM 3 30.Os 31.Sh NAME 32.Nm elf_getarsym 33.Nd retrieve the symbol table of an archive 34.Sh LIBRARY 35.Lb libelf 36.Sh SYNOPSIS 37.In libelf.h 38.Ft "Elf_Arsym *" 39.Fn elf_getarsym "Elf *elf" "size_t *ptr" 40.Sh DESCRIPTION 41The function 42.Fn elf_getarsym 43retrieves the symbol table for an 44.Xr ar 1 45archive, if one is available. 46.Pp 47Argument 48.Fa elf 49should be a descriptor for an 50.Xr ar 1 51archive opened using 52.Fn elf_begin 53or 54.Fn elf_memory . 55.Pp 56If the archive 57.Fa elf 58contains a symbol table with n entries, this function returns a 59pointer to an array of n+1 60.Vt Elf_Arsym 61structures. 62An 63.Vt Elf_Arsym 64structure has the following elements: 65.Bl -tag -width indent -compact 66.It Vt "char *" Va as_name 67This structure member is a pointer to a null-terminated symbol name. 68.It Vt "off_t" Va as_off 69This structure member contains the byte offset from the beginning of the archive to 70the header for the archive member. 71This value is suitable for use with 72.Xr elf_rand 3 . 73.It Vt "unsigned long" Va as_hash 74This structure member contains a portable hash value for the symbol 75name, as computed by 76.Xr elf_hash 3 . 77.El 78.Pp 79The last entry of the returned array will have a 80.Dv NULL 81value for member 82.Va as_name , 83a zero value for member 84.Va as_off 85and an illegal value of ~0UL for 86.Va as_hash . 87.Pp 88If argument 89.Fa ptr 90is non-null, the 91.Fn elf_getarsym 92function will store the number of table entries returned (including the 93sentinel entry at the end) into the location it points to. 94.Sh RETURN VALUES 95Function 96.Fn elf_getarsym 97returns a pointer to an array of 98.Vt Elf_Arsym 99structures if successful, or a 100.Dv NULL 101pointer if an error was encountered. 102.Pp 103If argument 104.Fa ptr 105is non-null and there was no error, the library will store the 106number of archive symbol entries returned into the location it 107points to. 108If argument 109.Fa ptr 110is non-null and an error was encountered, the library will 111set the location pointed to by it to zero. 112.Sh ERRORS 113Function 114.Fn elf_getarsym 115may fail with the following errors: 116.Bl -tag -width "[ELF_E_RESOURCE]" 117.It Bq Er ELF_E_ARGUMENT 118Argument 119.Fa elf 120was 121.Dv NULL . 122.It Bq Er ELF_E_ARGUMENT 123Argument 124.Fa elf 125was not a descriptor for an 126.Xr ar 1 127archive. 128.El 129.Sh SEE ALSO 130.Xr elf 3 , 131.Xr elf_begin 3 , 132.Xr elf_getarhdr 3 , 133.Xr elf_hash 3 , 134.Xr elf_memory 3 , 135.Xr elf_next 3 , 136.Xr elf_rand 3 137