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_getdyn.3 3734 2019-04-22 14:10:49Z jkoshy $
25.\"
26.Dd April 22, 2019
27.Dt GELF_GETDYN 3
28.Os
29.Sh NAME
30.Nm gelf_getdyn ,
31.Nm gelf_update_dyn
32.Nd read and update ELF dynamic entries
33.Sh LIBRARY
34.Lb libelf
35.Sh SYNOPSIS
36.In gelf.h
37.Ft "GElf_Dyn *"
38.Fn gelf_getdyn "Elf_Data *data" "int ndx" "GElf_Dyn *dyn"
39.Ft int
40.Fn gelf_update_dyn "Elf_Data *data" "int ndx" "GElf_Dyn *dyn"
41.Sh DESCRIPTION
42These convenience functions are used to retrieve and update class-dependent
43.Vt Elf32_Dyn
44or
45.Vt Elf64_Dyn
46information in the
47.Sy dynamic
48table of an ELF object.
49.Pp
50Argument
51.Ar data
52is an
53.Vt Elf_Data
54descriptor associated with a section of type
55.Dv SHT_DYNAMIC .
56Argument
57.Ar ndx
58is the index of the entry being retrieved or updated.
59The class-independent
60.Vt GElf_Dyn
61structure is described in
62.Xr gelf 3 .
63.Pp
64Function
65.Fn gelf_getdyn
66retrieves the class-dependent entry at index
67.Ar ndx
68in data buffer
69.Ar data
70and copies it to the destination pointed to by argument
71.Ar dyn
72after translation to class-independent form.
73.Pp
74Function
75.Fn gelf_update_dyn
76converts the class-independent entry pointed to
77by argument
78.Ar dyn
79to class-dependent form, and writes it to the entry at index
80.Ar ndx
81in the data buffer described by argument
82.Ar data .
83Function
84.Fn gelf_update_dyn
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_getdyn
91returns the value of argument
92.Ar dyn
93if successful, or NULL in case of an error.
94Function
95.Fn gelf_update_dyn
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 dyn
105were NULL.
106.It Bq Er ELF_E_ARGUMENT
107Argument
108.Ar ndx
109was less than zero or larger than the number of entries in the data
110descriptor.
111.It Bq Er ELF_E_ARGUMENT
112Data descriptor
113.Ar data
114was not associated with a section of type
115.Dv SHT_DYNAMIC .
116.It Bq Er ELF_E_RANGE
117A value was not representable in the target type.
118.It Bq Er ELF_E_VERSION
119The
120.Vt Elf_Data
121descriptor denoted by argument
122.Ar data
123is associated with an ELF object with an unsupported version.
124.El
125.El
126.Sh SEE ALSO
127.Xr elf 3 ,
128.Xr elf_getdata 3 ,
129.Xr elf_getscn 3 ,
130.Xr gelf 3
131