| blob | a71fea7594a8d8702128748b3ca0e8b268c92fef |
1 .\" $NetBSD: elf_update.3,v 1.2 2014/03/09 16:58:04 christos Exp $
2 .\"
3 .\" Copyright (c) 2006-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_update.3 1729 2011-08-14 09:13:00Z jkoshy
27 .\"
28 .Dd August 14, 2011
29 .Os
30 .Dt ELF_UPDATE 3
31 .Sh NAME
32 .Nm elf_update
33 .Nd update an ELF descriptor
34 .Sh LIBRARY
35 .Lb libelf
36 .Sh SYNOPSIS
37 .In libelf.h
38 .Ft off_t
39 .Fn elf_update "Elf *elf" "Elf_Cmd cmd"
40 .Sh DESCRIPTION
41 Function
42 .Fn elf_update
43 causes the library to recalculate the structure of an ELF
44 object and optionally write out the image of the object
45 to file.
46 .Pp
47 Argument
48 .Ar elf
49 should reference a valid ELF descriptor.
50 .Pp
51 Argument
52 .Ar cmd
53 can be one of the following values:
54 .Bl -tag -width "Dv ELF_C_WRITE"
55 .It Dv ELF_C_NULL
56 The library will recalculate structural information flagging
57 modified structures with the
58 .Dv ELF_F_DIRTY
59 flag, but will not write data to the underlying file image.
60 .It Dv ELF_C_WRITE
61 The library will recalculate structural information and will
62 also write the new image to the underlying file.
63 The ELF descriptor referenced by argument
64 .Ar elf
65 should permit the underlying ELF object to be written or updated
66 (see
67 .Xr elf_begin 3 ) .
68 .El
69 .Pp
70 All pointers to
71 .Vt Elf_Scn
72 and
73 .Vt Elf_Data
74 descriptors associated with descriptor
75 .Ar elf
76 should be considered invalid after a call to
77 .Fn elf_update .
78 .Ss Specifying Object Layout
79 The
80 .Lb libelf
81 supports two layout modes.
82 .Bl -tag -width indent
83 .It "Library Layout"
84 If the
85 .Dv ELF_F_LAYOUT
86 flag is not set on the ELF descriptor, the ELF library will lay out
87 the ELF object according to the following scheme:
88 .Bl -tag -compact -width "Section Data"
89 .It Em EHDR
90 The ELF executable header will be placed at the start of the object.
91 .It Em PHDR
92 If the ELF descriptor contains a program header table, it will be
93 placed after the Executable Header.
94 .It Em Section Data
95 ELF section data, if any, will be placed next, keeping each section's
96 alignment requirements in mind.
97 .It Em SHDR
98 The ELF section header table, if any, will be placed last.
99 .El
100 .It "Application Controlled Layout"
101 The application can take full control of the layout of the ELF object
102 by setting the
103 .Dv ELF_F_LAYOUT
104 flag on the ELF descriptor (see
105 .Xr elf_flagelf 3 ) .
106 In this case the library will lay out the ELF object using
107 application-supplied information as below:
108 .Pp
109 .Bl -tag -compact -width "Section Data"
110 .It Em EHDR
111 The ELF executable header will be placed at the start of the object.
112 .It Em PHDR
113 The ELF program header table, if any, it will be placed at the offset
114 specified in the
115 .Va e_phoff
116 field of the ELF executable header.
117 .It Em Section Data
118 The data for each ELF section will be placed at the offset specified
119 by the
120 .Va sh_offset
121 field of the section's header.
122 The size of the section will be taken from the
123 .Va sh_size
124 field of the section header.
125 .It Em SHDR
126 The ELF section header table, if any, will be placed at the offset
127 specified by the
128 .Va e_shoff
129 field of the executable header.
130 .El
131 .El
132 .Pp
133 Gaps in the coverage of the file's contents will be set to the fill value
134 specified by
135 .Xr elf_fill 3 .
136 .Ss Application Supplied Information
137 The application needs to set the following fields in the data
138 structures associated with the ELF descriptor prior to calling
139 .Fn elf_update .
140 .Bl -tag -width indent
141 .It "Executable Header"
142 The fields of the ELF executable header that need to be set by the
143 application are:
144 .Pp
145 .Bl -tag -width "e_ident[EI_OSABI]" -compact
146 .It Va e_entry
147 To be set to the desired entry address for executables.
148 .It Va e_flags
149 To be set to the desired processor specific flags.
150 .It Va "e_ident[EI_DATA]"
151 Must be set to one of
152 .Dv ELFDATA2LSB
153 or
154 .Dv ELFDATA2MSB .
155 .It Va "e_ident[EI_OSABI]"
156 To be set to the OS ABI desired.
157 For example, for
158 .Fx
159 executables, this field should be set to
160 .Dv ELFOSABI_FREEBSD .
161 .It Va e_machine
162 To be set to the desired machine architecture, one of the
163 .Dv EM_*
164 values in the header file
165 .In elfdefinitions.h .
166 .It Va e_phoff
167 If the application is managing the object's layout, it must
168 set this field to the file offset of the ELF program header table.
169 .It Va e_shoff
170 If the application is managing the object's layout, it must
171 set this field to the file offset of the ELF section header table.
172 .It Va e_shstrndx
173 To be set to the index of the string table containing
174 section names.
175 .It Va e_type
176 To be set to the type of the ELF object, one of the
177 .Dv ET_*
178 values in the header file
179 .In elfdefinitions.h .
180 .It Va e_version
181 To be set to the desired version of the ELF object.
182 .El
183 .It "Program Header"
184 All fields of the entries in the program header table need to be
185 set by the application.
186 .It "Section Header"
187 The fields of ELF section headers that need to be set by the
188 application are:
189 .Pp
190 .Bl -tag -width "sh_addralign" -compact
191 .It Va sh_addr
192 To be set to the memory address where the section should reside.
193 .It Va sh_addralign
194 If the application is managing the file layout, it must set this
195 field to the desired alignment for the section's contents.
196 This value must be a power of two and must be at least as large as the
197 largest alignment needed by any
198 .Vt Elf_Data
199 descriptor associated with the section.
200 .It Va sh_entsize
201 To be set to the size of each entry, for sections containing fixed size
202 elements, or set to zero for sections without fixed size elements.
203 If the application is not managing file layout, it may leave this
204 field as zero for those sections whose types are known to the library.
205 .It Va sh_flags
206 To be set to the desired section flags.
207 .It Va sh_info
208 To be set as described in
209 .Xr elf 5 .
210 .It Va sh_link
211 To be set as described in
212 .Xr elf 5 .
213 .It Va sh_name
214 To be set to the index of the section's name in the string table
215 containing section names.
216 .It Va sh_offset
217 If the application is managing the file layout, it must set this
218 field to the file offset of the section's contents.
219 .It Va sh_size
220 If the application is managing the file layout, it must set this
221 field to the file size of the section's contents.
222 .It Va sh_type
223 To be set to the type of the section.
224 .El
225 .It "Section Data"
226 The
227 .Vt Elf_Data
228 descriptors associated with each section specify its contents
229 (see
230 .Xr elf_getdata 3 ) .
231 While all the fields in these descriptors are under application
232 control, the following fields influence object layout:
233 .Bl -tag -width "Va d_align" -compact
234 .It Va d_align
235 To be set to the desired alignment, within the containing section, of
236 the descriptor's data.
237 .It Va d_off
238 If the application is managing object layout, it must set this field
239 to the file offset, within the section, at which the descriptor's data
240 should be placed.
241 .It Va d_size
242 To be set to the size in bytes of the memory representation of the
243 descriptor's data.
244 .El
245 .El
246 .Sh RETURN VALUES
247 Function
248 .Fn elf_update
249 returns the total size of the file image if successful, or -1 if an
250 error occurred.
251 .Sh ERRORS
252 This function may fail with the following errors:
253 .Bl -tag -width "[ELF_E_RESOURCE]"
254 .It Bq Er ELF_E_ARGUMENT
255 Argument
256 .Ar elf
257 was null.
258 .It Bq Er ELF_E_ARGUMENT
259 Argument
260 .Ar cmd
261 was not recognized.
262 .It Bq Er ELF_E_ARGUMENT
263 The argument
264 .Ar elf
265 was not a descriptor for an ELF object.
266 .It Bq Er ELF_E_CLASS
267 The
268 .Va e_ident[EI_CLASS]
269 field of the executable header of argument
270 .Ar elf
271 did not match the class of the file.
272 .It Bq Er ELF_E_DATA
273 An
274 .Vt Elf_Data
275 descriptor contained in argument
276 .Ar elf
277 specified an unsupported type.
278 .It Bq Er ELF_E_DATA
279 An
280 .Vt Elf_Data
281 descriptor specified an alignment that was zero or was not a power of
282 two.
283 .It Bq Er ELF_E_HEADER
284 The ELF header in argument
285 .Ar elf
286 requested a different byte order from the byte order already
287 associated with the file.
288 .It Bq Er ELF_E_IO
289 An I/O error was encountered.
290 .It Bq Er ELF_E_LAYOUT
291 An
292 .Vt Elf_Data
293 descriptor contained in argument
294 .Ar elf
295 specified an alignment incompatible with its containing section.
296 .It Bq Er ELF_E_LAYOUT
297 Argument
298 .Ar elf
299 contained section descriptors that overlapped in extent.
300 .It Bq Er ELF_E_LAYOUT
301 Argument
302 .Ar elf
303 contained section descriptors that were incorrectly aligned or were
304 too small for their data.
305 .It Bq Er ELF_E_LAYOUT
306 The flag
307 .Dv ELF_F_LAYOUT
308 was set on the Elf descriptor and the executable header overlapped
309 with the program header table.
310 .It Bq Er ELF_E_LAYOUT
311 The flag
312 .Dv ELF_F_LAYOUT
313 was set on the Elf descriptor and the program header table was placed
314 at a misaligned file offset.
315 .It Bq Er ELF_E_LAYOUT
316 The flag
317 .Dv ELF_F_LAYOUT
318 was set on the Elf descriptor and the section header table overlapped
319 an extent mapped by a section descriptor.
320 .It Bq Er ELF_E_LAYOUT
321 The
322 .Dv ELF_F_LAYOUT
323 flag was set on the Elf descriptor, and the
324 .Va d_offset
325 field in an
326 .Vt Elf_Data
327 descriptor contained a value that was not a multiple of the
328 descriptor's specified alignment.
329 .It Bq Er ELF_E_MODE
330 An
331 .Dv ELF_C_WRITE
332 operation was requested with an ELF descriptor that was not opened for
333 writing or updating.
334 .It Bq Er ELF_E_SECTION
335 Argument
336 .Ar elf
337 contained a section with an unrecognized type.
338 .It Bq Er ELF_E_SECTION
339 The section header at index
340 .Dv SHN_UNDEF
341 had an illegal section type.
342 .It Bq Er ELF_E_SEQUENCE
343 An
344 .Dv ELF_C_WRITE
345 operation was requested after a prior call to
346 .Fn elf_cntl elf ELF_C_FDDONE
347 disassociated the ELF descriptor
348 .Ar elf
349 from its underlying file.
350 .It Bq Er ELF_E_VERSION
351 Argument
352 .Ar elf
353 had an unsupported version or contained an
354 .Vt Elf_Data
355 descriptor with an unsupported version.
356 .El
357 .Sh SEE ALSO
358 .Xr elf 3 ,
359 .Xr elf32_getehdr 3 ,
360 .Xr elf32_getphdr 3 ,
361 .Xr elf32_newehdr 3 ,
362 .Xr elf32_newphdr 3 ,
363 .Xr elf64_getehdr 3 ,
364 .Xr elf64_getphdr 3 ,
365 .Xr elf64_newehdr 3 ,
366 .Xr elf64_newphdr 3 ,
367 .Xr elf_begin 3 ,
368 .Xr elf_cntl 3 ,
369 .Xr elf_fill 3 ,
370 .Xr elf_flagehdr 3 ,
371 .Xr elf_flagelf 3 ,
372 .Xr elf_getdata 3 ,
373 .Xr elf_getscn 3 ,
374 .Xr elf_newdata 3 ,
375 .Xr elf_newscn 3 ,
376 .Xr elf_rawdata 3 ,
377 .Xr gelf 3 ,
378 .Xr gelf_newehdr 3 ,
379 .Xr gelf_newphdr 3 ,
380 .Xr elf 5