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