1 .\" Copyright (c) 2006,2008-2011 Joseph Koshy. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
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.
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
24 .\" $Id: elf_begin.3 3182 2015-04-10 16:08:10Z emaste $
31 .Nd open an ELF file or ar(1) archive
37 .Fn elf_begin "int fd" "Elf_Cmd cmd" "Elf *elf"
41 is used to open ELF files and
43 archives for further processing by other APIs in the
46 It is also used to access individual ELF members of an
48 archive in combination with the
56 is an open file descriptor returned from an
63 for reading or writing depending on the value of argument
67 is primarily used for iterating through archives.
71 can have the following values:
72 .Bl -tag -width "ELF_C_WRITE"
81 are ignored, and no additional error is signalled.
83 This value is to be when the application wishes to examine (but not
84 modify) the contents of the file specified by the arguments
88 It can be used for both
90 archives and for ELF objects.
94 is NULL, the library will allocate a new ELF descriptor for the file
98 should have been opened for reading.
102 is not NULL, and references a regular ELF file previously opened with
104 then the activation count for the descriptor referenced by argument
107 The value in argument
109 should match that used to open the descriptor argument
114 is not NULL, and references a descriptor for an
116 archive opened earlier with
118 a descriptor for an element in the archive is returned as
119 described in the section
120 .Sx "Processing ar(1) archives"
122 The value for argument
124 should match that used to open the archive earlier.
128 is not NULL, and references an
130 archive opened earlier with
132 then the value of the argument
136 This command is used to prepare an ELF file for reading and writing.
137 This command is not supported for
143 should have been opened for reading and writing.
146 is NULL, the library will allocate a new ELF descriptor for
147 the file being processed.
150 is non-null, it should point to a descriptor previously
153 with the same values for arguments
157 in this case the library will increment the activation count for descriptor
159 and return the same descriptor.
161 Changes to the in-memory image of the ELF file may be written back to
166 This command is used when the application wishes to create a new ELF
170 should have been opened for writing.
173 is ignored, and the previous contents of file referenced by argument
177 .Ss Processing ar(1) archives
180 archive may be opened in read mode (with argument
188 The returned ELF descriptor can be passed into to
191 to access individual members of the archive.
193 Random access within an opened archive is possible using
200 The symbol table of the archive may be retrieved
204 The function returns a pointer to a ELF descriptor if successful, or NULL
205 if an error occurred.
207 To iterate through the members of an
210 .Bd -literal -offset indent
215 if ((ar_e = elf_begin(fd, c, (Elf *) 0)) == 0) {
216 \&... handle error in opening the archive ...
218 while ((elf_e = elf_begin(fd, c, ar_e)) != 0) {
219 \&... process member referenced by elf_e here ...
225 To create a new ELF file, use:
226 .Bd -literal -offset indent
230 if ((fd = open("filename", O_RDWR|O_TRUNC|O_CREAT, 0666)) < 0) {
231 \&... handle the error from open(2) ...
233 if ((e = elf_begin(fd, ELF_C_WRITE, (Elf *) 0)) == 0) {
234 \&... handle the error from elf_begin() ...
236 \&... create the ELF image using other elf(3) APIs ...
237 elf_update(e, ELF_C_WRITE);
243 can fail with the following errors:
244 .Bl -tag -width "[ELF_E_RESOURCE]"
245 .It Bq Er ELF_E_ARCHIVE
246 The archive denoted by argument
249 .It Bq Er ELF_E_ARGUMENT
250 The value in argument
253 .It Bq Er ELF_E_ARGUMENT
254 A non-null value for argument
260 .It Bq Er ELF_E_ARGUMENT
261 The value of argument
263 differs from the one the ELF descriptor
266 .It Bq Er ELF_E_ARGUMENT
269 differs from the value specified when ELF descriptor
272 .It Bq Er ELF_E_ARGUMENT
275 archive was opened with
279 .It Bq Er ELF_E_ARGUMENT
280 The file referenced by argument
283 .It Bq Er ELF_E_ARGUMENT
284 The underlying file for argument
286 was of an unsupported type.
288 The file descriptor in argument
292 The file descriptor in argument
294 could not be read or written to.
295 .It Bq Er ELF_E_RESOURCE
296 An out of memory condition was encountered.
297 .It Bq Er ELF_E_SEQUENCE
300 was called before a working version was established with
302 .It Bq Er ELF_E_VERSION
303 The ELF object referenced by argument
305 was of an unsupported ELF version.