contrib/elftoolchain/libelf/elf_update.3

   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: elf_update.3 3734 2019-04-22 14:10:49Z jkoshy $
  25 .\"
  26 .Dd April 22, 2019
  27 .Dt ELF_UPDATE 3
  28 .Os
  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_UNIMPL
 349 Argument
 350 .Ar elf
 351 contained a section with an unsupported ELF type.
 352 .It Bq Er ELF_E_VERSION
 353 Argument
 354 .Ar elf
 355 had an unsupported version or contained an
 356 .Vt Elf_Data
 357 descriptor with an unsupported version.
 358 .El
 359 .Sh SEE ALSO
 360 .Xr elf 3 ,
 361 .Xr elf32_getehdr 3 ,
 362 .Xr elf32_getphdr 3 ,
 363 .Xr elf32_newehdr 3 ,
 364 .Xr elf32_newphdr 3 ,
 365 .Xr elf64_getehdr 3 ,
 366 .Xr elf64_getphdr 3 ,
 367 .Xr elf64_newehdr 3 ,
 368 .Xr elf64_newphdr 3 ,
 369 .Xr elf_begin 3 ,
 370 .Xr elf_cntl 3 ,
 371 .Xr elf_fill 3 ,
 372 .Xr elf_flagehdr 3 ,
 373 .Xr elf_flagelf 3 ,
 374 .Xr elf_getdata 3 ,
 375 .Xr elf_getscn 3 ,
 376 .Xr elf_newdata 3 ,
 377 .Xr elf_newscn 3 ,
 378 .Xr elf_rawdata 3 ,
 379 .Xr gelf 3 ,
 380 .Xr gelf_newehdr 3 ,
 381 .Xr gelf_newphdr 3 ,
 382 .Xr elf 5