1.\"	$NetBSD: gelf_getsymshndx.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: gelf_getsymshndx.3 189 2008-07-20 10:38:08Z jkoshy
27.\"
28.Dd November 5, 2006
29.Os
30.Dt GELF_GETSYMSHNDX 3
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.Ar symdata
65is an
66.Vt Elf_Data
67descriptor associated with a section of type
68.Dv SHT_SYMTAB .
69Argument
70.Ar xndxdata
71is an
72.Vt Elf_Data
73descriptor associated with a section of type
74.Dv SHT_SYMTAB_SHNDX .
75Argument
76.Ar ndx
77is the index of the symbol table entry being retrieved or updated.
78Argument
79.Ar 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.Ar ndx
91from the data descriptor specified by argument
92.Ar symdata
93and stores in class-independent form in argument
94.Ar sym .
95In addition it retrieves the extended section index for the
96symbol from data buffer
97.Ar xndxdata
98and stores it into the location pointed to by argument
99.Ar xndxptr .
100.Pp
101Function
102.Fn gelf_update_symshndx
103updates the underlying symbol table entry in data
104descriptor
105.Ar symdata
106with the information in argument
107.Ar sym .
108In addition it sets the extended section index in
109data buffer
110.Ar xndxdata
111to the value of argument
112.Ar xndx .
113.Sh RETURN VALUES
114Function
115.Fn gelf_getsymshndx
116returns the value of argument
117.Ar sym
118if successful, or NULL in case of an error.
119.Pp
120Function
121.Fn gelf_update_symshndx
122returns a non-zero value if successful, or zero in case of an error.
123.Sh ERRORS
124These functions may fail with the following errors:
125.Bl -tag -width "[ELF_E_RESOURCE]"
126.It Bq Er ELF_E_ARGUMENT
127Arguments
128.Ar symdata ,
129.Ar xndxdata ,
130.Ar xndxptr
131or
132.Ar sym
133were NULL.
134.It Bq Er ELF_E_ARGUMENT
135Argument
136.Ar ndx
137was less than zero, or too large for either of descriptors
138.Ar symdata
139or
140.Ar xndxdata .
141.It Bq Er ELF_E_ARGUMENT
142Data descriptor
143.Ar symdata
144was not associated with a section of type
145.Dv SHT_SYMTAB .
146.It Bq Er ELF_E_ARGUMENT
147Data descriptor
148.Ar xndxdata
149was not associated with a section of type
150.Dv SHT_SYMTAB_SHNDX .
151.It Bq Er ELF_E_ARGUMENT
152Data descriptor
153.Ar symdata
154and
155.Ar xndxdata
156were associated with different ELF objects.
157.El
158.Sh SEE ALSO
159.Xr elf 3 ,
160.Xr elf_getdata 3 ,
161.Xr elf_getscn 3 ,
162.Xr gelf 3 ,
163.Xr gelf_getsym 3 ,
164.Xr gelf_update_sym 3
165