1 .\" Copyright (c) 2006-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_update.3 1729 2011-08-14 09:13:00Z jkoshy $
31 .Nd update an ELF descriptor
37 .Fn elf_update "Elf *elf" "Elf_Cmd cmd"
41 causes the library to recalculate the structure of an ELF
42 object and optionally write out the image of the object
47 should reference a valid ELF descriptor.
51 can be one of the following values:
52 .Bl -tag -width "Dv ELF_C_WRITE"
54 The library will recalculate structural information flagging
55 modified structures with the
57 flag, but will not write data to the underlying file image.
59 The library will recalculate structural information and will
60 also write the new image to the underlying file.
61 The ELF descriptor referenced by argument
63 should permit the underlying ELF object to be written or updated
72 descriptors associated with descriptor
74 should be considered invalid after a call to
76 .Ss Specifying Object Layout
79 supports two layout modes.
80 .Bl -tag -width indent
84 flag is not set on the ELF descriptor, the ELF library will lay out
85 the ELF object according to the following scheme:
86 .Bl -tag -compact -width "Section Data"
88 The ELF executable header will be placed at the start of the object.
90 If the ELF descriptor contains a program header table, it will be
91 placed after the Executable Header.
93 ELF section data, if any, will be placed next, keeping each section's
94 alignment requirements in mind.
96 The ELF section header table, if any, will be placed last.
98 .It "Application Controlled Layout"
99 The application can take full control of the layout of the ELF object
102 flag on the ELF descriptor (see
103 .Xr elf_flagelf 3 ) .
104 In this case the library will lay out the ELF object using
105 application-supplied information as below:
107 .Bl -tag -compact -width "Section Data"
109 The ELF executable header will be placed at the start of the object.
111 The ELF program header table, if any, it will be placed at the offset
114 field of the ELF executable header.
116 The data for each ELF section will be placed at the offset specified
119 field of the section's header.
120 The size of the section will be taken from the
122 field of the section header.
124 The ELF section header table, if any, will be placed at the offset
127 field of the executable header.
131 Gaps in the coverage of the file's contents will be set to the fill value
134 .Ss Application Supplied Information
135 The application needs to set the following fields in the data
136 structures associated with the ELF descriptor prior to calling
138 .Bl -tag -width indent
139 .It "Executable Header"
140 The fields of the ELF executable header that need to be set by the
143 .Bl -tag -width "e_ident[EI_OSABI]" -compact
145 To be set to the desired entry address for executables.
147 To be set to the desired processor specific flags.
148 .It Va "e_ident[EI_DATA]"
149 Must be set to one of
153 .It Va "e_ident[EI_OSABI]"
154 To be set to the OS ABI desired.
157 executables, this field should be set to
158 .Dv ELFOSABI_FREEBSD .
160 To be set to the desired machine architecture, one of the
162 values in the header file
163 .In elfdefinitions.h .
165 If the application is managing the object's layout, it must
166 set this field to the file offset of the ELF program header table.
168 If the application is managing the object's layout, it must
169 set this field to the file offset of the ELF section header table.
171 To be set to the index of the string table containing
174 To be set to the type of the ELF object, one of the
176 values in the header file
177 .In elfdefinitions.h .
179 To be set to the desired version of the ELF object.
182 All fields of the entries in the program header table need to be
183 set by the application.
185 The fields of ELF section headers that need to be set by the
188 .Bl -tag -width "sh_addralign" -compact
190 To be set to the memory address where the section should reside.
192 If the application is managing the file layout, it must set this
193 field to the desired alignment for the section's contents.
194 This value must be a power of two and must be at least as large as the
195 largest alignment needed by any
197 descriptor associated with the section.
199 To be set to the size of each entry, for sections containing fixed size
200 elements, or set to zero for sections without fixed size elements.
201 If the application is not managing file layout, it may leave this
202 field as zero for those sections whose types are known to the library.
204 To be set to the desired section flags.
206 To be set as described in
209 To be set as described in
212 To be set to the index of the section's name in the string table
213 containing section names.
215 If the application is managing the file layout, it must set this
216 field to the file offset of the section's contents.
218 If the application is managing the file layout, it must set this
219 field to the file size of the section's contents.
221 To be set to the type of the section.
226 descriptors associated with each section specify its contents
228 .Xr elf_getdata 3 ) .
229 While all the fields in these descriptors are under application
230 control, the following fields influence object layout:
231 .Bl -tag -width "Va d_align" -compact
233 To be set to the desired alignment, within the containing section, of
234 the descriptor's data.
236 If the application is managing object layout, it must set this field
237 to the file offset, within the section, at which the descriptor's data
240 To be set to the size in bytes of the memory representation of the
247 returns the total size of the file image if successful, or -1 if an
250 This function may fail with the following errors:
251 .Bl -tag -width "[ELF_E_RESOURCE]"
252 .It Bq Er ELF_E_ARGUMENT
256 .It Bq Er ELF_E_ARGUMENT
260 .It Bq Er ELF_E_ARGUMENT
263 was not a descriptor for an ELF object.
264 .It Bq Er ELF_E_CLASS
266 .Va e_ident[EI_CLASS]
267 field of the executable header of argument
269 did not match the class of the file.
273 descriptor contained in argument
275 specified an unsupported type.
279 descriptor specified an alignment that was zero or was not a power of
281 .It Bq Er ELF_E_HEADER
282 The ELF header in argument
284 requested a different byte order from the byte order already
285 associated with the file.
287 An I/O error was encountered.
288 .It Bq Er ELF_E_LAYOUT
291 descriptor contained in argument
293 specified an alignment incompatible with its containing section.
294 .It Bq Er ELF_E_LAYOUT
297 contained section descriptors that overlapped in extent.
298 .It Bq Er ELF_E_LAYOUT
301 contained section descriptors that were incorrectly aligned or were
302 too small for their data.
303 .It Bq Er ELF_E_LAYOUT
306 was set on the Elf descriptor and the executable header overlapped
307 with the program header table.
308 .It Bq Er ELF_E_LAYOUT
311 was set on the Elf descriptor and the program header table was placed
312 at a misaligned file offset.
313 .It Bq Er ELF_E_LAYOUT
316 was set on the Elf descriptor and the section header table overlapped
317 an extent mapped by a section descriptor.
318 .It Bq Er ELF_E_LAYOUT
321 flag was set on the Elf descriptor, and the
325 descriptor contained a value that was not a multiple of the
326 descriptor's specified alignment.
330 operation was requested with an ELF descriptor that was not opened for
332 .It Bq Er ELF_E_SECTION
335 contained a section with an unrecognized type.
336 .It Bq Er ELF_E_SECTION
337 The section header at index
339 had an illegal section type.
340 .It Bq Er ELF_E_SEQUENCE
343 operation was requested after a prior call to
344 .Fn elf_cntl elf ELF_C_FDDONE
345 disassociated the ELF descriptor
347 from its underlying file.
348 .It Bq Er ELF_E_VERSION
351 had an unsupported version or contained an
353 descriptor with an unsupported version.
357 .Xr elf32_getehdr 3 ,
358 .Xr elf32_getphdr 3 ,
359 .Xr elf32_newehdr 3 ,
360 .Xr elf32_newphdr 3 ,
361 .Xr elf64_getehdr 3 ,
362 .Xr elf64_getphdr 3 ,
363 .Xr elf64_newehdr 3 ,
364 .Xr elf64_newphdr 3 ,