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