1.\" $NetBSD: gelf_getsymshndx.3,v 1.6 2024/03/03 17:37:34 christos Exp $ 2.\" 3.\" Copyright (c) 2006,2008,2020 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: gelf_getsymshndx.3 3958 2022-03-12 14:31:32Z jkoshy 27.\" 28.Dd September 26, 2020 29.Dt GELF_GETSYMSHNDX 3 30.Os 31.Sh NAME 32.Nm gelf_getsymshndx , 33.Nm gelf_update_symshndx 34.Nd read and update symbol information using extended section indices 35.Sh LIBRARY 36.Lb libelf 37.Sh SYNOPSIS 38.In gelf.h 39.Ft "GElf_Sym *" 40.Fo gelf_getsymshndx 41.Fa "Elf_Data *symdata" 42.Fa "Elf_Data *xndxdata" 43.Fa "int ndx" 44.Fa "GElf_Sym *sym" 45.Fa "Elf32_Word *xndxptr" 46.Fc 47.Ft int 48.Fo gelf_update_symshndx 49.Fa "Elf_Data *symdata" 50.Fa "Elf_Data *xndxdata" 51.Fa "int ndx" 52.Fa "GElf_Sym *sym" 53.Fa "Elf32_Word xndx" 54.Fc 55.Sh DESCRIPTION 56These functions are analogous to 57.Fn gelf_getsym 58and 59.Fn gelf_update_sym 60respectively, but are capable of handling symbol tables using extended 61section numbering. 62.Pp 63Argument 64.Fa symdata 65is an 66.Vt Elf_Data 67descriptor associated with a section of type 68.Dv SHT_SYMTAB . 69Argument 70.Fa xndxdata 71is an 72.Vt Elf_Data 73descriptor associated with a section of type 74.Dv SHT_SYMTAB_SHNDX . 75Argument 76.Fa ndx 77is the index of the symbol table entry being retrieved or updated. 78Argument 79.Fa sym 80is a pointer to a class-independent 81.Vt GElf_Sym 82structure. 83.Vt GElf_Sym 84structures are described in detail in 85.Xr gelf 3 . 86.Pp 87Function 88.Fn gelf_getsymshndx 89retrieves symbol information at index 90.Fa ndx 91from the data descriptor specified by argument 92.Fa symdata 93and stores it in class-independent form in argument 94.Fa sym . 95Additionally: 96.Bl -bullet 97.It 98If the arguments 99.Ad xndxdata 100and 101.Fa xndxptr 102are both not 103.Dv NULL , 104it retrieves the extended section index for the 105symbol from the data buffer pointed to by the 106argument 107.Fa xndxdata 108and stores it into the location pointed to by argument 109.Fa xndxptr . 110.It 111Otherwise, if the argument 112.Fa xndxptr 113is not 114.Dv NULL , 115a value of zero is stored into the location pointed to by 116argument 117.Fa xndxptr . 118.El 119.Pp 120Function 121.Fn gelf_update_symshndx 122updates the underlying symbol table entry in the data 123descriptor 124.Fa symdata 125with the information in argument 126.Fa sym . 127In addition it sets the extended section index in 128data buffer 129.Fa xndxdata 130to the value of argument 131.Fa xndx . 132.Sh RETURN VALUES 133Function 134.Fn gelf_getsymshndx 135returns the value of argument 136.Fa sym 137if successful, or 138.Dv NULL 139in case of an error. 140.Pp 141Function 142.Fn gelf_update_symshndx 143returns a non-zero value if successful, or zero in case of an error. 144.Sh ERRORS 145These functions may fail with the following errors: 146.Bl -tag -width "[ELF_E_RESOURCE]" 147.It Bq Er ELF_E_ARGUMENT 148Arguments 149.Fa symdata , 150.Fa xndxdata , 151.Fa xndxptr 152or 153.Fa sym 154were 155.Dv NULL . 156.It Bq Er ELF_E_ARGUMENT 157Argument 158.Fa ndx 159was less than zero, or too large for either of descriptors 160.Fa symdata 161or 162.Fa xndxdata . 163.It Bq Er ELF_E_ARGUMENT 164Data descriptor 165.Fa symdata 166was not associated with a section of type 167.Dv SHT_SYMTAB . 168.It Bq Er ELF_E_ARGUMENT 169Data descriptor 170.Fa xndxdata 171was not associated with a section of type 172.Dv SHT_SYMTAB_SHNDX . 173.It Bq Er ELF_E_ARGUMENT 174Data descriptor 175.Fa symdata 176and 177.Fa xndxdata 178were associated with different ELF objects. 179.It Bq Er ELF_E_VERSION 180The 181.Vt Elf_Data 182descriptors denoted by arguments 183.Fa symdata 184and 185.Fa xndxdata 186are associated with an ELF object with an unsupported version. 187.El 188.Sh SEE ALSO 189.Xr elf 3 , 190.Xr elf_getdata 3 , 191.Xr elf_getscn 3 , 192.Xr gelf 3 , 193.Xr gelf_getsym 3 , 194.Xr gelf_update_sym 3 195