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