lib/libelf/elf.3

   1 .\" Copyright (c) 2006,2007 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 October 21, 2007
  27 .Os
  28 .Dt ELF 3
  29 .Sh NAME
  30 .Nm elf
  31 .Nd API for manipulating ELF objects
  32 .Sh LIBRARY
  33 .Lb libelf
  34 .Sh SYNOPSIS
  35 .In libelf.h
  36 .Sh DESCRIPTION
  37 The
  38 .Lb libelf
  39 library provides functions that allow an application to read and
  40 manipulate ELF object files, and to read
  41 .Xr ar 1
  42 archives.
  43 The library allows the manipulation of ELF objects in a byte ordering
  44 and word-size independent way, allowing an application to read and
  45 create ELF objects for 32 and 64 bit architectures and for little-
  46 and big-endian machines.
  47 The library is capable of processing ELF objects that use extended
  48 section numbering.
  49 .Pp
  50 This manual page serves to provide an overview of the functionality in
  51 the ELF library.
  52 Further information may found in the manual pages for individual
  53 .Xr ELF 3
  54 functions that comprise the library.
  55 .Ss ELF Concepts
  56 As described in
  57 .Xr elf 5 ,
  58 ELF files contain several data structures that are laid out in a
  59 specific way.
  60 ELF files begin with an
  61 .Dq Executable Header ,
  62 and may contain an optional
  63 .Dq Program Header Table ,
  64 and optional data in the form of ELF
  65 .Dq sections .
  66 A
  67 .Dq Section Header Table
  68 describes the content of the data in these sections.
  69 .Pp
  70 ELF objects have an associated
  71 .Dq "ELF class"
  72 which denotes the natural machine word size for the architecture
  73 the object is associated with.
  74 Objects for 32 bit architectures have an ELF class of
  75 .Dv ELFCLASS32 .
  76 Objects for 64 bit architectures have an ELF class of
  77 .Dv ELFCLASS64 .
  78 .Pp
  79 ELF objects also have an associated
  80 .Dq endianness
  81 which denotes the endianness of the machine architecture associated
  82 with the object.
  83 This may be
  84 .Dv ELFDATA2LSB
  85 for little-endian architectures and
  86 .Dv ELFDATA2MSB
  87 for big-endian architectures.
  88 .Pp
  89 ELF objects are also associated with an API version number.
  90 This version number determines the layout of the individual components
  91 of an ELF file and the semantics associated with these.
  92 .Ss Data Representation And Translation
  93 The
  94 .Xr ELF 3
  95 library distinguishes between
  96 .Dq native
  97 representations of ELF data structures and their
  98 .Dq file
  99 representations.
 100 .Pp
 101 An application would work with ELF data in its
 102 .Dq native
 103 representation, i.e., using the native byteorder and alignment mandated
 104 by the processor the application is running on.
 105 The
 106 .Dq file
 107 representation of the same data could use a different byte ordering
 108 and follow different constraints on object alignment than these native
 109 constraints.
 110 .Pp
 111 Accordingly, the
 112 .Xr ELF 3
 113 library offers translation facilities
 114 .Xr ( elf32_xlatetof 3 ,
 115 .Xr elf32_xlatetom 3 ,
 116 .Xr elf64_xlatetof 3
 117 and
 118 .Xr elf64_xlatetom 3 )
 119 to and from these
 120 representations and also provides higher-level APIs that retrieve and store
 121 data from the ELF object in a transparent manner.
 122 .Ss Library Working Version
 123 Conceptually, there are three version numbers associated with an
 124 application using the ELF library to manipulate ELF objects:
 125 .Bl -bullet -compact -offset indent
 126 .It
 127 The ELF version that the application was compiled against.
 128 This version determines the ABI expected by the application.
 129 .It
 130 The ELF version of the ELF object being manipulated by the
 131 application through the ELF library.
 132 .It
 133 The ELF version (or set of versions) supported by the ELF library itself.
 134 .El
 135 .Pp
 136 In order to facilitate working with ELF objects of differing versions,
 137 the ELF library requires the application to call the
 138 .Fn elf_version
 139 function before invoking many of its operations, in order to inform
 140 the library of the application's desired working version.
 141 .Pp
 142 In the current implementation, all three versions have to be
 143 .Dv EV_CURRENT .
 144 .Ss Namespace use
 145 The ELF library uses the following prefixes:
 146 .Bl -tag -width "ELF_F_*"
 147 .It elf_*
 148 Used for class-independent functions.
 149 .It elf32_*
 150 Used for functions working with 32 bit ELF objects.
 151 .It elf64_*
 152 Used for functions working with 64 bit ELF objects.
 153 .It Elf_*
 154 Used for class-independent data types.
 155 .It ELF_C_*
 156 Used for command values used in a few functions.
 157 These symbols are defined as members of the
 158 .Vt Elf_Cmd
 159 enumeration.
 160 .It ELF_E_*
 161 Used for error numbers.
 162 .It ELF_F_*
 163 Used for flags.
 164 .It ELF_K_*
 165 These constants define the kind of file associated with an ELF
 166 descriptor.
 167 See
 168 .Xr elf_kind 3 .
 169 The symbols are defined by the
 170 .Vt Elf_Kind
 171 enumeration.
 172 .It ELF_T_*
 173 These values are defined by the
 174 .Vt Elf_Type
 175 enumeration, and denote the types of ELF data structures
 176 that can be present in an ELF object.
 177 .El
 178 .Ss Descriptors
 179 Applications communicate with the library using descriptors.
 180 These are:
 181 .Bl -tag -width ".Vt Elf_Data"
 182 .It Vt Elf
 183 An
 184 .Vt Elf
 185 descriptor represents an ELF object or an
 186 .Xr ar 1
 187 archive.
 188 It is allocated using one of the
 189 .Fn elf_begin
 190 or
 191 .Fn elf_memory
 192 functions.
 193 An
 194 .Vt Elf
 195 descriptor can be used to read and write data to an ELF file.
 196 An
 197 .Vt Elf
 198 descriptor can be associated with zero or more
 199 .Vt Elf_Scn
 200 section descriptors.
 201 .Pp
 202 Given an ELF descriptor, the application may retrieve the ELF
 203 object's class-dependent
 204 .Dq "Executable Header"
 205 structures using the
 206 .Fn elf32_getehdr
 207 or
 208 .Fn elf64_getehdr
 209 functions.
 210 A new Ehdr structure may be allocated using the
 211 .Fn elf64_newehdr
 212 or
 213 .Fn elf64_newehdr
 214 functions.
 215 .Pp
 216 The
 217 .Dq "Program Header Table"
 218 associated with an ELF descriptor may be allocated using the
 219 .Fn elf32_getphdr
 220 or
 221 .Fn elf64_getphdr
 222 functions.
 223 A new program header table may be allocated or an existing table
 224 resized using the
 225 .Fn elf32_newphdr
 226 or
 227 .Fn elf64_newphdr
 228 functions.
 229 .Pp
 230 The
 231 .Vt Elf
 232 structure is opaque and has no members visible to the
 233 application.
 234 .\" TODO describe the Elf_Arhdr and Elf_Arsym structures.
 235 .It Vt Elf_Data
 236 An
 237 .Vt Elf_Data
 238 data structure describes an individual chunk of a ELF file as
 239 represented in memory.
 240 It has the following application visible members:
 241 .Bl -tag -width ".Vt unsigned int d_version" -compact
 242 .It Vt "uint64_t d_align"
 243 The in-file alignment of the data buffer within its containing ELF section.
 244 This value must be a power of two.
 245 .It Vt "uint64_t d_off"
 246 The offset with the containing section where this descriptors data
 247 would be placed.
 248 This field will be computed by the library unless the application
 249 requests full control of the ELF object's layout.
 250 .It Vt "uint64_t d_size"
 251 The number of bytes of data in this descriptor.
 252 .It Vt "void *d_buf"
 253 A pointer to data in memory.
 254 .It Vt "Elf_Type d_type"
 255 The ELF type (see below) of the data in this descriptor.
 256 .It Vt "unsigned int d_version"
 257 The operating version for the data in this buffer.
 258 .El
 259 .Pp
 260 .Vt Elf_Data
 261 descriptors are usually associated with
 262 .Vt Elf_Scn
 263 descriptors.
 264 Existing data descriptors associated with an ELF section may be
 265 structures are retrieved using the
 266 .Fn elf_getdata
 267 function.
 268 The
 269 .Fn elf_newdata
 270 function may be used to attach new data descriptors to an ELF section.
 271 .It Vt Elf_Scn
 272 .Vt Elf_Scn
 273 descriptors represent a section in an ELF object.
 274 .Pp
 275 They are retrieved using the
 276 .Fn elf_getscn
 277 function.
 278 An application may iterate through the existing sections of an ELF
 279 object using the
 280 .Fn elf_nextscn
 281 function.
 282 New sections may be allocated using the
 283 .Fn elf_newscn
 284 function.
 285 .Pp
 286 The
 287 .Vt Elf_Scn
 288 descriptor is opaque and contains no application modifiable fields.
 289 .El
 290 .Ss Supported Elf Types
 291 The following ELF datatypes are supported by the library.
 292 .Pp
 293 .Bl -tag -width ".Dv ELF_T_SYMINFO" -compact
 294 .It Dv ELF_T_ADDR
 295 Machine addresses.
 296 .It Dv ELF_T_BYTE
 297 Byte data.
 298 The library will not attempt to translate byte data.
 299 .It Dv ELF_T_CAP
 300 Software and hardware capability records.
 301 .It Dv ELF_T_DYN
 302 Records used in a section of type
 303 .Dv SHT_DYNAMIC .
 304 .It Dv ELF_T_EHDR
 305 ELF executable header.
 306 .It Dv ELF_T_HALF
 307 16-bit unsigned words.
 308 .It Dv ELF_T_LWORD
 309 64 bit unsigned words.
 310 .It Dv ELF_T_MOVE
 311 ELF Move records.
 312 .\".It Dv ELF_T_MOVEP
 313 .\" As yet unsupported.
 314 .It Dv ELF_T_NOTE
 315 ELF Note structures.
 316 .It Dv ELF_T_OFF
 317 File offsets.
 318 .It Dv ELF_T_PHDR
 319 ELF program header table entries.
 320 .It Dv ELF_T_REL
 321 ELF relocation entries.
 322 .It Dv ELF_T_RELA
 323 ELF relocation entries with addends.
 324 .It Dv ELF_T_SHDR
 325 ELF section header entries.
 326 .It Dv ELF_T_SWORD
 327 Signed 32-bit words.
 328 .It Dv ELF_T_SXWORD
 329 Signed 64-bit words.
 330 .It Dv ELF_T_SYMINFO
 331 ELF symbol information.
 332 .It Dv ELF_T_SYM
 333 ELF symbol table entries.
 334 .It Dv ELF_T_VDEF
 335 Symbol version definition records.
 336 .It Dv ELF_T_VNEED
 337 Symbol version requirement records.
 338 .It Dv ELF_T_WORD
 339 Unsigned 32-bit words.
 340 .It Dv ELF_T_XWORD
 341 Unsigned 64-bit words.
 342 .El
 343 .Pp
 344 The symbol
 345 .Dv ELF_T_NUM
 346 denotes the number of Elf types known to the library.
 347 .Pp
 348 The following table shows the mapping between ELF section types
 349 defined in
 350 .Xr elf 5
 351 and the types supported by the library.
 352 .Bl -column ".Dv SHT_PREINIT_ARRAY" ".Dv ELF_T_SYMINFO"
 353 .It Em Section Type Ta Em "Library Type" Ta Em Description
 354 .It Dv SHT_DYNAMIC Ta Dv ELF_T_DYN Ta Xo
 355 .Sq .dynamic
 356 section entries.
 357 .Xc
 358 .It Dv SHT_DYNSYM Ta Dv ELF_T_SYM Ta Symbols for dynamic linking.
 359 .It Dv SHT_FINI_ARRAY Ta Dv ELF_T_ADDR Ta Termination function pointers.
 360 .It Dv SHT_GROUP Ta Dv ELF_T_WORD Ta Section group marker.
 361 .It Dv SHT_HASH Ta Dv ELF_T_HASH Ta Symbol hashes.
 362 .It Dv SHT_INIT_ARRAY Ta Dv ELF_T_ADDR Ta Initialization function pointers.
 363 .It Dv SHT_NOBITS Ta Dv ELF_T_BYTE Ta Xo
 364 Empty sections.
 365 See
 366 .Xr elf 5 .
 367 .Xc
 368 .It Dv SHT_NOTE Ta Dv ELF_T_NOTE Ta ELF note records.
 369 .It Dv SHT_PREINIT_ARRAY Ta Dv ELF_T_ADDR Ta Pre-initialization function pointers.
 370 .It Dv SHT_PROGBITS Ta Dv ELF_T_BYTE Ta Machine code.
 371 .It Dv SHT_REL Ta Dv ELF_T_REL Ta ELF relocation records.
 372 .It Dv SHT_RELA Ta Dv ELF_T_RELA Ta Relocation records with addends.
 373 .It Dv SHT_STRTAB Ta Dv ELF_T_BYTE Ta String tables.
 374 .It Dv SHT_SYMTAB Ta Dv ELF_T_SYM Ta Symbol tables.
 375 .It Dv SHT_SYMTAB_SHNDX Ta Dv ELF_T_WORD Ta Used with extended section numbering.
 376 .It Dv SHT_GNU_verdef Ta Dv ELF_T_VDEF Ta Symbol version definitions.
 377 .It Dv SHT_GNU_verneed Ta Dv ELF_T_VNEED Ta Symbol versioning requirements.
 378 .It Dv SHT_GNU_versym Ta Dv ELF_T_HALF Ta Version symbols.
 379 .It Dv SHT_SUNW_move Ta Dv ELF_T_MOVE Ta ELF move records.
 380 .It Dv SHT_SUNW_syminfo Ta Dv ELF_T_SYMINFO Ta Additional symbol flags.
 381 .El
 382 .Ss Functional Grouping
 383 This section contains a brief overview of the available functionality
 384 in the ELF library.
 385 Each function listed here is described further in its own manual page.
 386 .Bl -tag -width indent
 387 .It "Archive Access"
 388 .Bl -tag -compact
 389 .It Fn elf_getarsym
 390 Retrieve the archive symbol table.
 391 .It Fn elf_getarhdr
 392 Retrieve the archive header for an object.
 393 .It Fn elf_getbase
 394 Retrieve the offset of a member inside an archive.
 395 .It Fn elf_next
 396 Iterate through an
 397 .Xr ar 1
 398 archive.
 399 .It Fn elf_rand
 400 Random access inside an
 401 .Xr ar 1
 402 archive.
 403 .El
 404 .It "Data Structures"
 405 .Bl -tag -compact
 406 .It Fn elf_getdata
 407 Retrieve translated data for an ELF section.
 408 .It Fn elf_getscn
 409 Retrieve the section descriptor for a named section.
 410 .It Fn elf_ndxscn
 411 Retrieve the index for a section.
 412 .It Fn elf_newdata
 413 Add a new
 414 .Vt Elf_Data
 415 descriptor to an ELF section.
 416 .It Fn elf_newscn
 417 Add a new section descriptor to an ELF descriptor.
 418 .It Fn elf_nextscn
 419 Iterate through the sections in an ELF object.
 420 .It Fn elf_rawdata
 421 Retrieve untranslated data for an ELF sectino.
 422 .It Fn elf_rawfile
 423 Return a pointer to the untranslated file contents for an ELF object.
 424 .It Fn elf32_getehdr , Fn elf64_getehdr
 425 Retrieve the Executable Header in an ELF object.
 426 .It Fn elf32_getphdr , Fn elf64_getphdr
 427 Retrieve the Program Header Table in an ELF object.
 428 .It Fn elf32_getshdr , Fn elf64_getshdr
 429 Retrieve the ELF section header associated with an
 430 .Vt Elf_Scn
 431 descriptor.
 432 .It Fn elf32_newehdr , Fn elf64_newehdr
 433 Allocate an Executable Header in an ELF object.
 434 .It Fn elf32_newphdr , Fn elf64_newphdr
 435 Allocate or resize the Program Header Table in an ELF object.
 436 .El
 437 .It "Data Translation"
 438 .Bl -tag -compact
 439 .It Fn elf32_xlatetof , Fn elf64_xlatetof
 440 Translate an ELF data structure from its native representation to its
 441 file representation.
 442 .It Fn elf32_xlatetom , Fn elf64_xlatetom
 443 Translate an ELF data structure from its file representation to a
 444 native representation.
 445 .El
 446 .It "Error Reporting"
 447 .Bl -tag -compact
 448 .It Fn elf_errno
 449 Retrieve the current error.
 450 .It Fn elf_errmsg
 451 Retrieve a human readable description of the current error.
 452 .El
 453 .It "Initialization"
 454 .Bl -tag -compact
 455 .It Fn elf_begin
 456 Opens an
 457 .Xr ar 1
 458 archive or ELF object given a file descriptor.
 459 .It Fn elf_end
 460 Close an ELF descriptor and release all its resources.
 461 .It Fn elf_memory
 462 Opens an
 463 .Xr ar 1
 464 archive or ELF object present in a memory arena.
 465 .It Fn elf_version
 466 Sets the operating version.
 467 .El
 468 .It "IO Control"
 469 .Bl -tag -width ".Fn elf_setshstrndx" -compact
 470 .It Fn elf_cntl
 471 Manage the association between and ELF descriptor and its underlying file.
 472 .It Fn elf_flagdata
 473 Mark an
 474 .Vt Elf_Data
 475 descriptor as dirty.
 476 .It Fn elf_flagehdr
 477 Mark the ELF Executable Header in an ELF descriptor as dirty.
 478 .It Fn elf_flagphdr
 479 Mark the ELF Program Header Table in an ELF descriptor as dirty.
 480 .It Fn elf_flagscn
 481 Mark an
 482 .Vt Elf_Scn
 483 descriptor as dirty.
 484 .It Fn elf_flagshdr
 485 Mark an ELF Section Header as dirty.
 486 .It Fn elf_setshstrndx
 487 Set the index of the section name string table for the ELF object.
 488 .It Fn elf_update
 489 Recompute ELF object layout and optionally write the modified object
 490 back to the underlying file.
 491 .El
 492 .It "Queries"
 493 .Bl -tag -width ".Fn elf_getshstrndx" -compact
 494 .It Fn elf32_checksum , Fn elf64_checkum
 495 Compute checksum of an ELF object.
 496 .It Fn elf_getident
 497 Retrieve the identification bytes for an ELF object.
 498 .It Fn elf_getshnum
 499 Retrieve the number of sections in an ELF object.
 500 .It Fn elf_getshstrndx
 501 Retrieve the section index of the section name string table in
 502 an ELF object.
 503 .It Fn elf_hash
 504 Compute the ELF hash value of a string.
 505 .It Fn elf_kind
 506 Query the kind of object associated with an ELF descriptor.
 507 .It Fn elf32_fsize , Fn elf64_fsize
 508 Return the size of the file representation of an ELF type.
 509 .El
 510 .El
 511 .Ss Controlling ELF Object Layout
 512 In the usual mode of operation, library will compute section
 513 offsets and alignments based on the contents of an ELF descriptor's
 514 sections without need for further intervention by the
 515 application.
 516 .Pp
 517 However, if the application wishes to take complete charge of the
 518 layout of the ELF file, it may set the
 519 .Dv ELF_F_LAYOUT
 520 flag on an ELF descriptor using
 521 .Xr elf_flagelf 3 ,
 522 following which the library will use the data offsets and alignments
 523 specified by the application when laying out the file.
 524 Application control of file layout is described further in the
 525 .Xr elf_update 3
 526 manual page.
 527 .Pp
 528 Gaps in between sections will be filled with the fill character
 529 set by function
 530 .Fn elf_fill .
 531 .Ss Error Handling
 532 In case an error is encountered, these library functions set an
 533 internal error number and signal the presence of the error by
 534 returning an special return value.
 535 The application can check the
 536 current error number by calling
 537 .Xr elf_errno 3 .
 538 A human readable description of the recorded error is available by
 539 calling
 540 .Xr elf_errmsg 3 .
 541 .Ss Memory Management Rules
 542 The library keeps track of all
 543 .Vt Elf_Scn
 544 and
 545 .Vt Elf_Data
 546 descriptors associated with an ELF descriptor and recovers them
 547 when the descriptor is closed using
 548 .Xr elf_end 3 .
 549 Thus the application must not call
 550 .Xr free 3
 551 on data structures allocated by the ELF library.
 552 .Pp
 553 Conversely the library will not
 554 free data that it has not allocated.
 555 As an example, an application may call
 556 .Xr elf_newdata 3
 557 to allocate a new
 558 .Vt Elf_Data
 559 descriptor and can set the
 560 .Va d_off
 561 member of the descriptor to point to a region of memory allocated
 562 using
 563 .Xr malloc 3 .
 564 It is the applications responsibility to free this arena, though the
 565 library will reclaim the space used by the
 566 .Vt Elf_Data
 567 descriptor itself.
 568 .Sh SEE ALSO
 569 .Xr gelf 3 ,
 570 .Xr elf 5
 571 .Sh HISTORY
 572 The original ELF(3) API was developed for Unix System V.
 573 The current implementation of the ELF(3) API appeared in
 574 .Fx 7.0 .
 575 .Sh AUTHORS
 576 The ELF library was written by
 577 .An "Joseph Koshy"
 578 .Aq jkoshy@FreeBSD.org .