jcs.org
jcs's openbsd hax
openbsd
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: gelf_getsym.3,v 1.3 2025/06/10 17:19:45 schwarze Exp $
25.\"
26.Dd April 22, 2019
27.Dt GELF_GETSYM 3
28.Os
29.Sh NAME
30.Nm gelf_getsym ,
31.Nm gelf_update_sym
32.Nd read and update symbol information
33.Sh SYNOPSIS
34.Lb libelf
35.In gelf.h
36.Ft "GElf_Sym *"
37.Fn gelf_getsym "Elf_Data *data" "int ndx" "GElf_Sym *sym"
38.Ft int
39.Fn gelf_update_sym "Elf_Data *data" "int ndx" "GElf_Sym *sym"
40.Sh DESCRIPTION
41These convenience functions are used to retrieve and update class-dependent
42.Vt Elf32_Sym
43and
44.Vt Elf64_Sym
45structures in an ELF object.
46.Pp
47Argument
48.Ar data
49is an
50.Vt Elf_Data
51descriptor associated with a section of type
52.Dv SHT_SYMTAB ,
53.Dv SHT_DYNSYM
54or
55.Dv SHT_GNU_versym .
56Argument
57.Ar ndx
58is the index of the symbol being retrieved or updated.
59The class-independent
60.Vt GElf_Sym
61structure is described in
62.Xr gelf 3 .
63.Pp
64Function
65.Fn gelf_getsym
66retrieves class-dependent symbol information at index
67.Ar ndx
68in data buffer
69.Ar data
70and copies it to the destination pointed to by argument
71.Ar sym
72after translation to class-independent form.
73.Pp
74Function
75.Fn gelf_update_sym
76converts the class-independent symbol information pointed to
77by argument
78.Ar sym
79to class-dependent form, and writes it to the symbol entry at index
80.Ar ndx
81in the data buffer described by argument
82.Ar data .
83Function
84.Fn gelf_update_sym
85signals an error if any of the values in the class-independent
86representation exceeds the representable limits of the target
87type.
88.Sh RETURN VALUES
89Function
90.Fn gelf_getsym
91returns the value of argument
92.Ar sym
93if successful, or NULL in case of an error.
94Function
95.Fn gelf_update_sym
96returns a non-zero value if successful, or zero in case of an error.
97.Sh ERRORS
98These functions may fail with the following errors:
99.Bl -tag -width "[ELF_E_RESOURCE]"
100.It Bq Er ELF_E_ARGUMENT
101Arguments
102.Ar data
103or
104.Ar sym
105were NULL.
106.It Bq Er ELF_E_ARGUMENT
107Argument
108.Ar ndx
109was less than zero or larger than the number of symbols in the data
110descriptor.
111.It Bq Er ELF_E_ARGUMENT
112Data descriptor
113.Ar data
114was not associated with a section containing symbol information.
115.It Bq Er ELF_E_RANGE
116A value was not representable in the target type.
117.It Bq Er ELF_E_VERSION
118The
119.Vt Elf_Data
120descriptor denoted by argument
121.Ar data
122is associated with an ELF object with an unsupported version.
123.El
124.Sh SEE ALSO
125.Xr elf 3 ,
126.Xr elf_getdata 3 ,
127.Xr elf_getscn 3 ,
128.Xr gelf 3 ,
129.Xr gelf_getsyminfo 3 ,
130.Xr gelf_update_syminfo 3