jcs.org
jcs's openbsd hax
openbsd
1.\" Copyright (c) 2006,2008,2010-2011 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: elf_getdata.3,v 1.3 2025/06/10 17:19:45 schwarze Exp $
25.\"
26.Dd April 22, 2019
27.Dt ELF_GETDATA 3
28.Os
29.Sh NAME
30.Nm elf_getdata ,
31.Nm elf_newdata ,
32.Nm elf_rawdata
33.Nd iterate through or allocate section data
34.Sh SYNOPSIS
35.Lb libelf
36.In libelf.h
37.Ft "Elf_Data *"
38.Fn elf_getdata "Elf_Scn *scn" "Elf_Data *data"
39.Ft "Elf_Data *"
40.Fn elf_newdata "Elf_Scn *scn"
41.Ft "Elf_Data *"
42.Fn elf_rawdata "Elf_Scn *scn" "Elf_Data *data"
43.Sh DESCRIPTION
44These functions are used to access and manipulate data descriptors
45associated with section descriptors.
46Data descriptors used by the ELF library are described in
47.Xr elf 3 .
48.Pp
49Function
50.Fn elf_getdata
51will return the next data descriptor associated with section descriptor
52.Ar scn .
53The returned data descriptor will be setup to contain translated data.
54Argument
55.Ar data
56may be NULL, in which case the function returns the first data descriptor
57associated with section
58.Ar scn .
59If argument
60.Ar data
61is not NULL, it must be a pointer to a data descriptor associated with
62section descriptor
63.Ar scn ,
64and function
65.Fn elf_getdata
66will return a pointer to the next data descriptor for the section,
67or NULL when the end of the section's descriptor list is reached.
68.Pp
69Function
70.Fn elf_newdata
71will allocate a new data descriptor and append it to the list of data
72descriptors associated with section descriptor
73.Ar scn .
74The new data descriptor will be initialized as follows:
75.Bl -tag -width "d_version" -compact -offset indent
76.It Va d_align
77Set to 1.
78.It Va d_buf
79Initialized to NULL.
80.It Va d_off
81Set to (off_t) -1.
82This field is under application control if the
83.Dv ELF_F_LAYOUT
84flag was set on the ELF descriptor.
85.It Va d_size
86Set to zero.
87.It Va d_type
88Initialized to
89.Dv ELF_T_BYTE .
90.It Va d_version
91Set to the current working version of the library, as set by
92.Xr elf_version 3 .
93.El
94The application must set these values as appropriate before
95calling
96.Xr elf_update 3 .
97Section
98.Ar scn
99must be associated with an ELF file opened for writing.
100If the application has not requested full control of layout by
101setting the
102.Dv ELF_F_LAYOUT
103flag on descriptor
104.Ar elf ,
105then the data referenced by the returned descriptor will be positioned
106after the existing content of the section, honoring the file alignment
107specified in member
108.Va d_align .
109On successful completion of a call to
110.Fn elf_newdata ,
111the ELF library will mark the section
112.Ar scn
113as
114.Dq dirty .
115.Pp
116Function
117.Fn elf_rawdata
118is used to step through the data descriptors associated with
119section
120.Ar scn .
121In contrast to function
122.Fn elf_getdata ,
123this function returns untranslated data.
124If argument
125.Ar data
126is NULL, the first data descriptor associated with section
127.Ar scn
128is returned.
129If argument
130.Ar data
131is not NULL, is must be a data descriptor associated with
132section
133.Ar scn ,
134and function
135.Fn elf_rawdata
136will return the next data descriptor in the list, or NULL
137if no further descriptors are present.
138Function
139.Fn elf_rawdata
140always returns
141.Vt Elf_Data
142structures of type
143.Dv ELF_T_BYTE .
144.Ss Special handling of zero-sized and SHT_NOBITS sections
145For sections of type
146.Dv SHT_NOBITS ,
147and for zero-sized sections,
148the functions
149.Fn elf_getdata
150and
151.Fn elf_rawdata
152return a pointer to a valid
153.Vt Elf_Data
154structure that has its
155.Va d_buf
156member set to NULL and its
157.Va d_size
158member set to the size of the section.
159.Pp
160If an application wishes to create a section of type
161.Dv SHT_NOBITS ,
162it should add a data buffer to the section using function
163.Fn elf_newdata .
164It should then set the
165.Va d_buf
166and
167.Va d_size
168members of the returned
169.Vt Elf_Data
170structure to NULL and the desired size of the section respectively.
171.Sh RETURN VALUES
172These functions return a valid pointer to a data descriptor if successful, or
173NULL if an error occurs.
174.Sh ERRORS
175These functions may fail with the following errors:
176.Bl -tag -width "[ELF_E_RESOURCE]"
177.It Bq Er ELF_E_ARGUMENT
178Either of the arguments
179.Ar scn
180or
181.Ar data
182was NULL.
183.It Bq Er ELF_E_ARGUMENT
184The data descriptor referenced by argument
185.Ar data
186is not associated with section descriptor
187.Ar scn .
188.It Bq Er ELF_E_ARGUMENT
189The section denoted by argument
190.Ar scn
191had no data associated with it.
192.It Bq Er ELF_E_DATA
193Retrieval of data from the underlying object failed.
194.It Bq Er ELF_E_RESOURCE
195An out of memory condition was detected.
196.It Bq Er ELF_E_SECTION
197Section
198.Ar scn
199had type
200.Dv SHT_NULL .
201.It Bq Er ELF_E_SECTION
202The type of the section
203.Ar scn
204was not recognized by the library.
205.It Bq Er ELF_E_SECTION
206The size of the section
207.Ar scn
208is not a multiple of the file size for its section type.
209.It Bq Er ELF_E_SECTION
210The file offset for section
211.Ar scn
212is incorrect.
213.It Bq Er ELF_E_UNIMPL
214The section type associated with section
215.Ar scn
216is not supported.
217.It Bq Er ELF_E_VERSION
218Section
219.Ar scn
220was associated with an ELF object with an unsupported
221version.
222.El
223.Sh SEE ALSO
224.Xr elf 3 ,
225.Xr elf_flagdata 3 ,
226.Xr elf_flagscn 3 ,
227.Xr elf_getscn 3 ,
228.Xr elf_getshdr 3 ,
229.Xr elf_newscn 3 ,
230.Xr elf_rawfile 3 ,
231.Xr elf_update 3 ,
232.Xr elf_version 3 ,
233.Xr gelf 3