1.\" $NetBSD: elf_getarsym.3,v 1.2 2014/03/09 16:58:04 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 189 2008-07-20 10:38:08Z jkoshy 27.\" 28.Dd August 15, 2006 29.Os 30.Dt ELF_GETARSYM 3 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.Ar 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.Ar 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 NULL value for member 80.Va as_name , 81a zero value for member 82.Va as_off 83and an illegal value of ~0UL for 84.Va as_hash . 85.Pp 86If argument 87.Ar ptr 88is non-null, the 89.Fn elf_getarsym 90function will store the number of table entries returned (including the 91sentinel entry at the end) into the location it points to. 92.Sh RETURN VALUES 93Function 94.Fn elf_getarsym 95returns a pointer to an array of 96.Vt Elf_Arsym 97structures if successful, or a NULL 98pointer if an error was encountered. 99.Pp 100If argument 101.Ar ptr 102is non-null and there was no error, the library will store the 103number of archive symbol entries returned into the location it 104points to. 105If argument 106.Ar ptr 107is non-null and an error was encountered, the library will 108set the location pointed to by it to zero. 109.Sh ERRORS 110Function 111.Fn elf_getarsym 112may fail with the following errors: 113.Bl -tag -width "[ELF_E_RESOURCE]" 114.It Bq Er ELF_E_ARGUMENT 115Argument 116.Ar elf 117was NULL. 118.It Bq Er ELF_E_ARGUMENT 119Argument 120.Ar elf 121was not a descriptor for an 122.Xr ar 1 123archive. 124.El 125.Sh SEE ALSO 126.Xr elf 3 , 127.Xr elf_begin 3 , 128.Xr elf_getarhdr 3 , 129.Xr elf_hash 3 , 130.Xr elf_memory 3 , 131.Xr elf_next 3 , 132.Xr elf_rand 3 133