external/bsd/libelf/dist/elf_update.3

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