lib/libelf/elf_update.3

   1 .\" Copyright (c) 2006,2007-2008 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 .\" $FreeBSD$
  25 .\"
  26 .Dd March 19, 2008
  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 is a descriptor to an ELF object.
  48 Argument
  49 .Ar cmd
  50 can take on the following values:
  51 .Bl -tag -width "ELF_C_WRITE"
  52 .It Dv ELF_C_NULL
  53 The library will recalculate structural information flagging
  54 modified structures with the
  55 .Dv ELF_F_DIRTY
  56 flag, but will not write back data to the underlying file image.
  57 .It Dv ELF_C_WRITE
  58 The library will recalculate structural information and will
  59 also write the new image to the underlying file.
  60 .El
  61 .Ss File Layout
  62 If the
  63 .Dv ELF_F_LAYOUT
  64 flag has been set on the ELF descriptor, the application assumes full
  65 responsibility for the layout of the ELF object.
  66 If this flag is not set, the ELF library will compute the layout of the
  67 file from its associated section descriptors.
  68 .Pp
  69 It is the application's responsibility to manage the following
  70 structure members in the ELF file:
  71 .Bl -tag -width indent
  72 .It "Executable Header"
  73 The ELF executable header is described in
  74 .Xr elf 5 .
  75 The following members of the ELF executable header are the application's
  76 responsibility:
  77 .Pp
  78 .Bl -tag -width "e_ident[EI_OSABI]" -compact
  79 .It Va e_entry
  80 Set to the desired entry address for executables.
  81 .It Va e_flags
  82 Set to the desired processor specific flags.
  83 .It Va "e_ident[EI_DATA]"
  84 Must be set to one of
  85 .Dv ELFDATA2LSB
  86 or
  87 .Dv ELFDATA2MSB .
  88 .It Va "e_ident[EI_OSABI]"
  89 Set to the OS ABI desired.
  90 For
  91 .Fx
  92 executables, this field should be set to
  93 .Dv ELFOSABI_FREEBSD .
  94 .It Va e_machine
  95 Set to the desired machine architecture, one of the
  96 .Dv EM_*
  97 values in
  98 .In sys/elf_common.h .
  99 .It Va e_phoff
 100 If the application is managing the object's layout, it must
 101 set this field to the file offset of the ELF program header table.
 102 .It Va e_shoff
 103 If the application is managing the object's layout, it must
 104 set this field to the file offset of the ELF section header table.
 105 .It Va e_shstrndx
 106 Set to the index of the string table containing
 107 section names.
 108 .It Va e_type
 109 Set to the type of the ELF object, one of the
 110 .Dv ET_*
 111 values in
 112 .In sys/elf_common.h .
 113 .It Va e_version
 114 Set to the desired version of the ELF object.
 115 .El
 116 .It "Program Header"
 117 All fields of the entries in the program header table are
 118 under application control.
 119 .It "Section Header"
 120 The ELF section header is described in
 121 .Xr elf 5 .
 122 The following members of the ELF section header are the
 123 application's responsibility:
 124 .Pp
 125 .Bl -tag -width "sh_addralign" -compact
 126 .It Va sh_addr
 127 Set to the physical memory address where the section should reside.
 128 .It Va sh_addralign
 129 If the application is managing the file layout, it must set this
 130 field to the desired alignment for the section's contents.
 131 This value must be a power of two.
 132 .It Va sh_entsize
 133 Set to the size of each entry, for sections containing fixed size
 134 elements, or set to zero for sections without fixed size elements.
 135 If the application is not managing file layout, it may leave this
 136 field as zero for those sections whose types known to the library.
 137 .It Va sh_flags
 138 Set to the desired section flags.
 139 .It Va sh_info
 140 Set as described in
 141 .Xr elf 5 .
 142 .It Va sh_link
 143 Set as described in
 144 .Xr elf 5 .
 145 .It Va sh_name
 146 Set to the index of the section's name in the string table containing
 147 section names.
 148 .It Va sh_offset
 149 If the application is managing the file layout, it must set this
 150 field to the file offset of the section's contents.
 151 .It Va sh_size
 152 If the application is managing the file layout, it must set this
 153 field to the file size of the section's contents.
 154 .It Va sh_type
 155 Set to the type of the section.
 156 .El
 157 .El
 158 .Pp
 159 Gaps in the coverage of the file's contents will be set to the fill value
 160 specified by
 161 .Xr elf_fill 3 .
 162 .Pp
 163 If the application has requested full control over the file's layout by
 164 setting the
 165 .Dv ELF_F_LAYOUT
 166 flag on the ELF descriptor, it should ensure that there are no
 167 gaps in the coverage of the file's contents.
 168 .Pp
 169 All pointers to
 170 .Vt Elf_Scn
 171 and
 172 .Vt Elf_Data
 173 descriptors associated with descriptor
 174 .Ar elf
 175 should be considered as invalid after a call to
 176 .Fn elf_update .
 177 .Sh RETURN VALUES
 178 Function
 179 .Fn elf_update
 180 returns the total size of the file image if successful, or -1 if an
 181 error occurred.
 182 .Sh ERRORS
 183 This function may fail with the following errors:
 184 .Bl -tag -width "[ELF_E_RESOURCE]"
 185 .It Bq Er ELF_E_ARGUMENT
 186 Argument
 187 .Ar elf
 188 was null.
 189 .It Bq Er ELF_E_ARGUMENT
 190 Argument
 191 .Ar cmd
 192 was not recognized.
 193 .It Bq Er ELF_E_ARGUMENT
 194 The argument
 195 .Ar elf
 196 was not a descriptor for an ELF object.
 197 .It Bq Er ELF_E_CLASS
 198 The
 199 .Va e_ident[EI_CLASS]
 200 field of the executable header of argument
 201 .Ar elf
 202 did not match the class of the file.
 203 .It Bq Er ELF_E_DATA
 204 An
 205 .Vt Elf_Data
 206 descriptor contained in argument
 207 .Ar elf
 208 specified a type incompatible with its containing section.
 209 .It Bq Er ELF_E_HEADER
 210 The ELF header in argument
 211 .Ar elf
 212 requested a different byte order from the byte order already
 213 associated with the file.
 214 .It Bq Er ELF_E_IO
 215 An I/O error was encountered.
 216 .It Bq Er ELF_E_LAYOUT
 217 An
 218 .Vt Elf_Data
 219 descriptor contained in argument
 220 .Ar elf
 221 specified an alignment incompatible with its containing section.
 222 .It Bq Er ELF_E_LAYOUT
 223 Argument
 224 .Ar elf
 225 contained section descriptors that overlapped in extent.
 226 .It Bq Er ELF_E_LAYOUT
 227 Argument
 228 .Ar elf
 229 contained section descriptors that were incorrectly aligned or were
 230 too small for their data.
 231 .It Bq Er ELF_E_LAYOUT
 232 The flag
 233 .Dv ELF_F_LAYOUT
 234 was set on the Elf descriptor and the section header table overlapped
 235 an extent in the object mapped by a section descriptor.
 236 .It Bq Er ELF_E_MODE
 237 An
 238 .Dv ELF_C_WRITE
 239 operation was requested with an ELF descriptor that was not opened for
 240 writing or updating.
 241 .It Bq Er ELF_E_SECTION
 242 Argument
 243 .Ar elf
 244 contained a section with an unrecognized type.
 245 .It Bq Er ELF_E_SECTION
 246 The section header at index
 247 .Dv SHN_UNDEF
 248 had an illegal section type.
 249 .It Bq Er ELF_E_SEQUENCE
 250 An
 251 .Dv ELF_C_WRITE
 252 operation was requested after a prior call to
 253 .Fn elf_cntl elf ELF_C_FDDONE
 254 disassociated the ELF descriptor
 255 .Ar elf
 256 from its underlying file.
 257 .It Bq Er ELF_E_VERSION
 258 Argument
 259 .Ar elf
 260 had an unsupported version or contained an
 261 .Vt Elf_Data
 262 descriptor with an unsupported version.
 263 .El
 264 .Sh SEE ALSO
 265 .Xr elf 3 ,
 266 .Xr elf32_getehdr 3 ,
 267 .Xr elf32_getphdr 3 ,
 268 .Xr elf32_newehdr 3 ,
 269 .Xr elf32_newphdr 3 ,
 270 .Xr elf64_getehdr 3 ,
 271 .Xr elf64_getphdr 3 ,
 272 .Xr elf64_newehdr 3 ,
 273 .Xr elf64_newphdr 3 ,
 274 .Xr elf_cntl 3 ,
 275 .Xr elf_fill 3 ,
 276 .Xr elf_flagehdr 3 ,
 277 .Xr elf_flagelf 3 ,
 278 .Xr elf_getdata 3 ,
 279 .Xr elf_getscn 3 ,
 280 .Xr elf_newdata 3 ,
 281 .Xr elf_newscn 3 ,
 282 .Xr elf_rawdata 3 ,
 283 .Xr gelf 3 ,
 284 .Xr gelf_newehdr 3 ,
 285 .Xr gelf_newphdr 3 ,
 286 .Xr elf 5