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