1  .\" Copyright (c) 2006,2008 Joseph Koshy.  All rights reserved.
  2  .\"
  3  .\" Redistribution and use in source and binary forms, with or without
  4  .\" modification, are permitted provided that the following conditions
  5  .\" are met:
  6  .\" 1. Redistributions of source code must retain the above copyright
  7  .\"    notice, this list of conditions and the following disclaimer.
  8  .\" 2. Redistributions in binary form must reproduce the above copyright
  9  .\"    notice, this list of conditions and the following disclaimer in the
 10  .\"    documentation and/or other materials provided with the distribution.
 11  .\"
 12  .\" This software is provided by Joseph Koshy ``as is'' and
 13  .\" any express or implied warranties, including, but not limited to, the
 14  .\" implied warranties of merchantability and fitness for a particular purpose
 15  .\" are disclaimed.  in no event shall Joseph Koshy be liable
 16  .\" for any direct, indirect, incidental, special, exemplary, or consequential
 17  .\" damages (including, but not limited to, procurement of substitute goods
 18  .\" or services; loss of use, data, or profits; or business interruption)
 19  .\" however caused and on any theory of liability, whether in contract, strict
 20  .\" liability, or tort (including negligence or otherwise) arising in any way
 21  .\" out of the use of this software, even if advised of the possibility of
 22  .\" such damage.
 23  .\"
 24  .\" $Id$
 25  .\"
 26  .Dd November 5, 2006
 27  .Os
 28  .Dt GELF_GETSYMSHNDX 3
 29  .Sh NAME
 30  .Nm gelf_getsymshndx ,
 31  .Nm gelf_update_symshndx
 32  .Nd read and update symbol information using extended section indices
 33  .Sh LIBRARY
 34  .Lb libelf
 35  .Sh SYNOPSIS
 36  .In gelf.h
 37  .Ft "GElf_Sym *"
 38  .Fo gelf_getsymshndx
 39  .Fa "Elf_Data *symdata"
 40  .Fa "Elf_Data *xndxdata"
 41  .Fa "int ndx"
 42  .Fa "GElf_Sym *sym"
 43  .Fa "Elf32_Word *xndxptr"
 44  .Fc
 45  .Ft int
 46  .Fo gelf_update_symshndx
 47  .Fa "Elf_Data *symdata"
 48  .Fa "Elf_Data *xndxdata"
 49  .Fa "int ndx"
 50  .Fa "GElf_Sym *sym"
 51  .Fa "Elf32_Word xndx"
 52  .Fc
 53  .Sh DESCRIPTION
 54  These functions are analogous to
 55  .Fn gelf_getsym
 56  and
 57  .Fn gelf_update_sym
 58  respectively, but are capable of handling symbol tables using extended
 59  section numbering.
 60  .Pp
 61  Argument
 62  .Ar symdata
 63  is an
 64  .Vt Elf_Data
 65  descriptor associated with a section of type
 66  .Dv SHT_SYMTAB .
 67  Argument
 68  .Ar xndxdata
 69  is an
 70  .Vt Elf_Data
 71  descriptor associated with a section of type
 72  .Dv SHT_SYMTAB_SHNDX .
 73  Argument
 74  .Ar ndx
 75  is the index of the symbol table entry being retrieved or updated.
 76  Argument
 77  .Ar sym
 78  is a pointer to a class-independent
 79  .Vt GElf_Sym
 80  structure.
 81  .Vt GElf_Sym
 82  structures are described in detail in
 83  .Xr gelf 3 .
 84  .Pp
 85  Function
 86  .Fn gelf_getsymshndx
 87  retrieves symbol information at index
 88  .Ar ndx
 89  from the data descriptor specified by argument
 90  .Ar symdata
 91  and stores in class-independent form in argument
 92  .Ar sym .
 93  In addition it retrieves the extended section index for the
 94  symbol from data buffer
 95  .Ar xndxdata
 96  and stores it into the location pointed to by argument
 97  .Ar xndxptr .
 98  .Pp
 99  Function
100  .Fn gelf_update_symshndx
101  updates the underlying symbol table entry in data
102  descriptor
103  .Ar symdata
104  with the information in argument
105  .Ar sym .
106  In addition it sets the extended section index in
107  data buffer
108  .Ar xndxdata
109  to the value of argument
110  .Ar xndx .
111  .Sh RETURN VALUES
112  Function
113  .Fn gelf_getsymshndx
114  returns the value of argument
115  .Ar sym
116  if successful, or NULL in case of an error.
117  .Pp
118  Function
119  .Fn gelf_update_symshndx
120  returns a non-zero value if successful, or zero in case of an error.
121  .Sh ERRORS
122  These functions may fail with the following errors:
123  .Bl -tag -width "[ELF_E_RESOURCE]"
124  .It Bq Er ELF_E_ARGUMENT
125  Arguments
126  .Ar symdata ,
127  .Ar xndxdata ,
128  .Ar xndxptr
129  or
130  .Ar sym
131  were NULL.
132  .It Bq Er ELF_E_ARGUMENT
133  Argument
134  .Ar ndx
135  was less than zero, or too large for either of descriptors
136  .Ar symdata
137  or
138  .Ar xndxdata .
139  .It Bq Er ELF_E_ARGUMENT
140  Data descriptor
141  .Ar symdata
142  was not associated with a section of type
143  .Dv SHT_SYMTAB .
144  .It Bq Er ELF_E_ARGUMENT
145  Data descriptor
146  .Ar xndxdata
147  was not associated with a section of type
148  .Dv SHT_SYMTAB_SHNDX .
149  .It Bq Er ELF_E_ARGUMENT
150  Data descriptor
151  .Ar symdata
152  and
153  .Ar xndxdata
154  were associated with different ELF objects.
155  .El
156  .Sh SEE ALSO
157  .Xr elf 3 ,
158  .Xr elf_getdata 3 ,
159  .Xr elf_getscn 3 ,
160  .Xr gelf 3 ,
161  .Xr gelf_getsym 3 ,
162  .Xr gelf_update_sym 3