jcs.org
jcs's openbsd hax
openbsd
1.\" Copyright (c) 2006,2008-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_begin.3,v 1.3 2025/06/10 17:19:45 schwarze Exp $
25.\"
26.Dd December 11, 2011
27.Dt ELF_BEGIN 3
28.Os
29.Sh NAME
30.Nm elf_begin
31.Nd open an ELF file or ar(1) archive
32.Sh SYNOPSIS
33.Lb libelf
34.In libelf.h
35.Ft "Elf *"
36.Fn elf_begin "int fd" "Elf_Cmd cmd" "Elf *elf"
37.Sh DESCRIPTION
38Function
39.Fn elf_begin
40is used to open ELF files and
41.Xr ar 1
42archives for further processing by other APIs in the
43.Xr elf 3
44library.
45It is also used to access individual ELF members of an
46.Xr ar 1
47archive in combination with the
48.Xr elf_next 3
49and
50.Xr elf_rand 3
51APIs.
52.Pp
53Argument
54.Ar fd
55is an open file descriptor returned from an
56.Xr open 2
57system call.
58Function
59.Fn elf_begin
60uses argument
61.Ar fd
62for reading or writing depending on the value of argument
63.Ar cmd .
64Argument
65.Ar elf
66is primarily used for iterating through archives.
67.Pp
68The argument
69.Ar cmd
70can have the following values:
71.Bl -tag -width "ELF_C_WRITE"
72.It ELF_C_NULL
73Causes
74.Fn elf_begin
75to return NULL.
76Arguments
77.Ar fd
78and
79.Ar elf
80are ignored, and no additional error is signalled.
81.It ELF_C_READ
82This value is to be when the application wishes to examine (but not
83modify) the contents of the file specified by the arguments
84.Ar fd
85and
86.Ar elf .
87It can be used for both
88.Xr ar 1
89archives and for ELF objects.
90.Pp
91If argument
92.Ar elf
93is NULL, the library will allocate a new ELF descriptor for the file
94being processed.
95The argument
96.Ar fd
97should have been opened for reading.
98.Pp
99If argument
100.Ar elf
101is not NULL, and references a regular ELF file previously opened with
102.Fn elf_begin ,
103then the activation count for the descriptor referenced by argument
104.Ar elf
105is incremented.
106The value in argument
107.Ar fd
108should match that used to open the descriptor argument
109.Ar elf .
110.Pp
111If argument
112.Ar elf
113is not NULL, and references a descriptor for an
114.Xr ar 1
115archive opened earlier with
116.Fn elf_begin ,
117a descriptor for an element in the archive is returned as
118described in the section
119.Sx "Processing ar(1) archives"
120below.
121The value for argument
122.Ar fd
123should match that used to open the archive earlier.
124.Pp
125If argument
126.Ar elf
127is not NULL, and references an
128.Xr ar 1
129archive opened earlier with
130.Fn elf_memory ,
131then the value of the argument
132.Ar fd
133is ignored.
134.It Dv ELF_C_RDWR
135This command is used to prepare an ELF file for reading and writing.
136This command is not supported for
137.Xr ar 1
138archives.
139.Pp
140Argument
141.Ar fd
142should have been opened for reading and writing.
143If argument
144.Ar elf
145is NULL, the library will allocate a new ELF descriptor for
146the file being processed.
147If the argument
148.Ar elf
149is non-null, it should point to a descriptor previously
150allocated with
151.Fn elf_begin
152with the same values for arguments
153.Ar fd
154and
155.Ar cmd ;
156in this case the library will increment the activation count for descriptor
157.Ar elf
158and return the same descriptor.
159.Pp
160Changes to the in-memory image of the ELF file may be written back to
161disk using the
162.Xr elf_update 3
163function.
164.It Dv ELF_C_WRITE
165This command is used when the application wishes to create a new ELF
166file.
167Argument
168.Ar fd
169should have been opened for writing.
170Argument
171.Ar elf
172is ignored, and the previous contents of file referenced by argument
173.Ar fd
174are overwritten.
175.El
176.Ss Processing ar(1) archives
177An
178.Xr ar 1
179archive may be opened in read mode (with argument
180.Ar cmd
181set to
182.Dv ELF_C_READ )
183using
184.Fn elf_begin
185or
186.Fn elf_memory .
187The returned ELF descriptor can be passed into to
188subsequent calls to
189.Fn elf_begin
190to access individual members of the archive.
191.Pp
192Random access within an opened archive is possible using
193the
194.Xr elf_next 3
195and
196.Xr elf_rand 3
197functions.
198.Pp
199The symbol table of the archive may be retrieved
200using
201.Xr elf_getarsym 3 .
202.Sh RETURN VALUES
203The function returns a pointer to a ELF descriptor if successful, or NULL
204if an error occurred.
205.Sh EXAMPLES
206To iterate through the members of an
207.Xr ar 1
208archive, use:
209.Bd -literal -offset indent
210Elf_Cmd c;
211Elf *ar_e, *elf_e;
212\&...
213c = ELF_C_READ;
214if ((ar_e = elf_begin(fd, c, (Elf *) 0)) == 0) {
215 \&... handle error in opening the archive ...
216}
217while ((elf_e = elf_begin(fd, c, ar_e)) != 0) {
218 \&... process member referenced by elf_e here ...
219 c = elf_next(elf_e);
220 elf_end(elf_e);
221}
222.Ed
223.Pp
224To create a new ELF file, use:
225.Bd -literal -offset indent
226int fd;
227Elf *e;
228\&...
229if ((fd = open("filename", O_RDWR|O_TRUNC|O_CREAT, 0666)) == -1) {
230 \&... handle the error from open(2) ...
231}
232if ((e = elf_begin(fd, ELF_C_WRITE, (Elf *) 0)) == 0) {
233 \&... handle the error from elf_begin() ...
234}
235\&... create the ELF image using other elf(3) APIs ...
236elf_update(e, ELF_C_WRITE);
237elf_end(e);
238.Ed
239.Sh ERRORS
240Function
241.Fn elf_begin
242can fail with the following errors:
243.Bl -tag -width "[ELF_E_RESOURCE]"
244.It Bq Er ELF_E_ARCHIVE
245The archive denoted by argument
246.Ar elf
247could not be parsed.
248.It Bq Er ELF_E_ARGUMENT
249The value in argument
250.Ar cmd
251was unrecognized.
252.It Bq Er ELF_E_ARGUMENT
253A non-null value for argument
254.Ar elf
255was specified when
256.Ar cmd
257was set to
258.Dv ELF_C_RDWR .
259.It Bq Er ELF_E_ARGUMENT
260The value of argument
261.Ar fd
262differs from the one the ELF descriptor
263.Ar elf
264was created with.
265.It Bq Er ELF_E_ARGUMENT
266Argument
267.Ar cmd
268differs from the value specified when ELF descriptor
269.Ar elf
270was created.
271.It Bq Er ELF_E_ARGUMENT
272An
273.Xr ar 1
274archive was opened with
275.Ar cmd
276set to
277.Dv ELF_C_RDWR .
278.It Bq Er ELF_E_ARGUMENT
279The file referenced by argument
280.Ar fd
281was empty.
282.It Bq Er ELF_E_ARGUMENT
283The underlying file for argument
284.Ar fd
285was of an unsupported type.
286.It Bq Er ELF_E_IO
287The file descriptor in argument
288.Ar fd
289was invalid.
290.It Bq Er ELF_E_IO
291The file descriptor in argument
292.Ar fd
293could not be read or written to.
294.It Bq Er ELF_E_RESOURCE
295An out of memory condition was encountered.
296.It Bq Er ELF_E_SEQUENCE
297Function
298.Fn elf_begin
299was called before a working version was established with
300.Xr elf_version 3 .
301.It Bq Er ELF_E_VERSION
302The ELF object referenced by argument
303.Ar fd
304was of an unsupported ELF version.
305.El
306.Sh SEE ALSO
307.Xr elf 3 ,
308.Xr elf_end 3 ,
309.Xr elf_errno 3 ,
310.Xr elf_memory 3 ,
311.Xr elf_next 3 ,
312.Xr elf_rand 3 ,
313.Xr elf_update 3 ,
314.Xr gelf 3