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