elf.3
1 .\" Copyright (c) 2006-2008,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 July 28, 2014 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 provides functions that allow an application to read and manipulate 40 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 Dv elf_ 148 Used for class-independent functions. 149 .It Dv elf32_ 150 Used for functions working with 32 bit ELF objects. 151 .It Dv elf64_ 152 Used for functions working with 64 bit ELF objects. 153 .It Dv Elf_ 154 Used for class-independent data types. 155 .It Dv ELF_C_ 156 Used for command values used in a few functions. 157 These symbols are defined as members of the 158 .Vt Dv Elf_Cmd 159 enumeration. 160 .It Dv ELF_E_ 161 Used for error numbers. 162 .It Dv ELF_F_ 163 Used for flags. 164 .It Dv 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 Dv 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 .Pp 179 In addition, the library uses symbols with prefixes 180 .Dv _ELF 181 and 182 .Dv _libelf 183 for its internal use. 184 .Ss Descriptors 185 Applications communicate with the library using descriptors. 186 These are: 187 .Bl -tag -width ".Vt Elf_Data" 188 .It Vt Elf 189 An 190 .Vt Elf 191 descriptor represents an ELF object or an 192 .Xr ar 1 193 archive. 194 It is allocated using one of the 195 .Fn elf_begin 196 or 197 .Fn elf_memory 198 functions. 199 An 200 .Vt Elf 201 descriptor can be used to read and write data to an ELF file. 202 An 203 .Vt Elf 204 descriptor can be associated with zero or more 205 .Vt Elf_Scn 206 section descriptors. 207 .Pp 208 Given an ELF descriptor, the application may retrieve the ELF 209 object's class-dependent 210 .Dq "Executable Header" 211 structures using the 212 .Fn elf32_getehdr 213 or 214 .Fn elf64_getehdr 215 functions. 216 A new Ehdr structure may be allocated using the 217 .Fn elf64_newehdr 218 or 219 .Fn elf64_newehdr 220 functions. 221 .Pp 222 The 223 .Dq "Program Header Table" 224 associated with an ELF descriptor may be allocated using the 225 .Fn elf32_getphdr 226 or 227 .Fn elf64_getphdr 228 functions. 229 A new program header table may be allocated or an existing table 230 resized using the 231 .Fn elf32_newphdr 232 or 233 .Fn elf64_newphdr 234 functions. 235 .Pp 236 The 237 .Vt Elf 238 structure is opaque and has no members visible to the 239 application. 240 .\" TODO describe the Elf_Arhdr and Elf_Arsym structures. 241 .It Vt Elf_Data 242 An 243 .Vt Elf_Data 244 data structure describes an individual chunk of a ELF file as 245 represented in memory. 246 It has the following application-visible members: 247 .Bl -tag -width ".Vt unsigned int d_version" -compact 248 .It Vt "uint64_t d_align" 249 The in-file alignment of the data buffer within its containing ELF section. 250 This value must be non-zero and a power of two. 251 .It Vt "void *d_buf" 252 A pointer to data in memory. 253 .It Vt "uint64_t d_off" 254 The offset within the containing section where this descriptor's data 255 would be placed. 256 This field will be computed by the library unless the application 257 requests full control of the ELF object's layout. 258 .It Vt "uint64_t d_size" 259 The number of bytes of data in this descriptor. 260 .It Vt "Elf_Type d_type" 261 The ELF type (see below) of the data in this descriptor. 262 .It Vt "unsigned int d_version" 263 The operating version for the data in this buffer. 264 .El 265 .Pp 266 .Vt Elf_Data 267 descriptors are usually associated with 268 .Vt Elf_Scn 269 descriptors. 270 Existing data descriptors associated with an ELF section may be 271 structures are retrieved using the 272 .Fn elf_getdata 273 and 274 .Fn elf_rawdata 275 functions. 276 The 277 .Fn elf_newdata 278 function may be used to attach new data descriptors to an ELF section. 279 .It Vt Elf_Scn 280 .Vt Elf_Scn 281 descriptors represent a section in an ELF object. 282 .Pp 283 They are retrieved using the 284 .Fn elf_getscn 285 function. 286 An application may iterate through the existing sections of an ELF 287 object using the 288 .Fn elf_nextscn 289 function. 290 New sections may be allocated using the 291 .Fn elf_newscn 292 function. 293 .Pp 294 The 295 .Vt Elf_Scn 296 descriptor is opaque and contains no application modifiable fields. 297 .El 298 .Ss Supported Elf Types 299 The following ELF datatypes are supported by the library. 300 .Pp 301 .Bl -tag -width ".Dv ELF_T_SYMINFO" -compact 302 .It Dv ELF_T_ADDR 303 Machine addresses. 304 .It Dv ELF_T_BYTE 305 Byte data. 306 The library will not attempt to translate byte data. 307 .It Dv ELF_T_CAP 308 Software and hardware capability records. 309 .It Dv ELF_T_DYN 310 Records used in a section of type 311 .Dv SHT_DYNAMIC . 312 .It Dv ELF_T_EHDR 313 ELF executable header. 314 .It Dv ELF_T_GNUHASH 315 GNU-style hash tables. 316 .It Dv ELF_T_HALF 317 16-bit unsigned words. 318 .It Dv ELF_T_LWORD 319 64 bit unsigned words. 320 .It Dv ELF_T_MOVE 321 ELF Move records. 322 .\".It Dv ELF_T_MOVEP 323 .\" As yet unsupported. 324 .It Dv ELF_T_NOTE 325 ELF Note structures. 326 .It Dv ELF_T_OFF 327 File offsets. 328 .It Dv ELF_T_PHDR 329 ELF program header table entries. 330 .It Dv ELF_T_REL 331 ELF relocation entries. 332 .It Dv ELF_T_RELA 333 ELF relocation entries with addends. 334 .It Dv ELF_T_SHDR 335 ELF section header entries. 336 .It Dv ELF_T_SWORD 337 Signed 32-bit words. 338 .It Dv ELF_T_SXWORD 339 Signed 64-bit words. 340 .It Dv ELF_T_SYMINFO 341 ELF symbol information. 342 .It Dv ELF_T_SYM 343 ELF symbol table entries. 344 .It Dv ELF_T_VDEF 345 Symbol version definition records. 346 .It Dv ELF_T_VNEED 347 Symbol version requirement records. 348 .It Dv ELF_T_WORD 349 Unsigned 32-bit words. 350 .It Dv ELF_T_XWORD 351 Unsigned 64-bit words. 352 .El 353 .Pp 354 The symbol 355 .Dv ELF_T_NUM 356 denotes the number of Elf types known to the library. 357 .Pp 358 The following table shows the mapping between ELF section types 359 defined in 360 .Xr elf 5 361 and the types supported by the library. 362 .Bl -column ".Dv SHT_PREINIT_ARRAY" ".Dv ELF_T_SYMINFO" 363 .It Em Section Type Ta Em "Library Type" Ta Em Description 364 .It Dv SHT_DYNAMIC Ta Dv ELF_T_DYN Ta Xo 365 .Sq .dynamic 366 section entries. 367 .Xc 368 .It Dv SHT_DYNSYM Ta Dv ELF_T_SYM Ta Symbols for dynamic linking. 369 .It Dv SHT_FINI_ARRAY Ta Dv ELF_T_ADDR Ta Termination function pointers. 370 .It Dv SHT_GNU_HASH Ta Dv ELF_T_GNUHASH Ta GNU hash sections. 371 .It Dv SHT_GNU_LIBLIST Ta Dv ELF_T_WORD Ta List of libraries to be pre-linked. 372 .It Dv SHT_GNU_verdef Ta Dv ELF_T_VDEF Ta Symbol version definitions. 373 .It Dv SHT_GNU_verneed Ta Dv ELF_T_VNEED Ta Symbol versioning requirements. 374 .It Dv SHT_GNU_versym Ta Dv ELF_T_HALF Ta Version symbols. 375 .It Dv SHT_GROUP Ta Dv ELF_T_WORD Ta Section group marker. 376 .It Dv SHT_HASH Ta Dv ELF_T_HASH Ta Symbol hashes. 377 .It Dv SHT_INIT_ARRAY Ta Dv ELF_T_ADDR Ta Initialization function pointers. 378 .It Dv SHT_NOBITS Ta Dv ELF_T_BYTE Ta Xo 379 Empty sections. 380 See 381 .Xr elf 5 . 382 .Xc 383 .It Dv SHT_NOTE Ta Dv ELF_T_NOTE Ta ELF note records. 384 .It Dv SHT_PREINIT_ARRAY Ta Dv ELF_T_ADDR Ta Pre-initialization function pointers. 385 .It Dv SHT_PROGBITS Ta Dv ELF_T_BYTE Ta Machine code. 386 .It Dv SHT_REL Ta Dv ELF_T_REL Ta ELF relocation records. 387 .It Dv SHT_RELA Ta Dv ELF_T_RELA Ta Relocation records with addends. 388 .It Dv SHT_STRTAB Ta Dv ELF_T_BYTE Ta String tables. 389 .It Dv SHT_SYMTAB Ta Dv ELF_T_SYM Ta Symbol tables. 390 .It Dv SHT_SYMTAB_SHNDX Ta Dv ELF_T_WORD Ta Used with extended section numbering. 391 .It Dv SHT_SUNW_dof Ta Dv ELF_T_BYTE Ta Xo 392 Used by 393 .Xr dtrace 1 . 394 .Xc 395 .It Dv SHT_SUNW_move Ta Dv ELF_T_MOVE Ta ELF move records. 396 .It Dv SHT_SUNW_syminfo Ta Dv ELF_T_SYMINFO Ta Additional symbol flags. 397 .It Dv SHT_SUNW_verdef Ta Dv ELF_T_VDEF Ta Xo 398 Same as 399 .Dv SHT_GNU_verdef . 400 .Xc 401 .It Dv SHT_SUNW_verneed Ta Dv ELF_T_VNEED Ta Xo 402 Same as 403 .Dv SHT_GNU_verneed . 404 .Xc 405 .It Dv SHT_SUNW_versym Ta Dv ELF_T_HALF Ta Xo 406 Same as 407 .Dv SHT_GNU_versym . 408 .Xc 409 .El 410 .Pp 411 Section types in the range 412 .Ns [ Dv SHT_LOOS , 413 .Dv SHT_HIUSER ] 414 are otherwise considered to be of type 415 .Dv ELF_T_BYTE . 416 .Ss Functional Grouping 417 This section contains a brief overview of the available functionality 418 in the ELF library. 419 Each function listed here is described further in its own manual page. 420 .Bl -tag -width indent 421 .It "Archive Access" 422 .Bl -tag -compact 423 .It Fn elf_getarsym 424 Retrieve the archive symbol table. 425 .It Fn elf_getarhdr 426 Retrieve the archive header for an object. 427 .It Fn elf_getbase 428 Retrieve the offset of a member inside an archive. 429 .It Fn elf_next 430 Iterate through an 431 .Xr ar 1 432 archive. 433 .It Fn elf_rand 434 Random access inside an 435 .Xr ar 1 436 archive. 437 .El 438 .It "Data Structures" 439 .Bl -tag -compact 440 .It Fn elf_getdata 441 Retrieve translated data for an ELF section. 442 .It Fn elf_getscn 443 Retrieve the section descriptor for a named section. 444 .It Fn elf_ndxscn 445 Retrieve the index for a section. 446 .It Fn elf_newdata 447 Add a new 448 .Vt Elf_Data 449 descriptor to an ELF section. 450 .It Fn elf_newscn 451 Add a new section descriptor to an ELF descriptor. 452 .It Fn elf_nextscn 453 Iterate through the sections in an ELF object. 454 .It Fn elf_rawdata 455 Retrieve untranslated data for an ELF section. 456 .It Fn elf_rawfile 457 Return a pointer to the untranslated file contents for an ELF object. 458 .It Fn elf32_getehdr , Fn elf64_getehdr 459 Retrieve the Executable Header in an ELF object. 460 .It Fn elf32_getphdr , Fn elf64_getphdr 461 Retrieve the Program Header Table in an ELF object. 462 .It Fn elf32_getshdr , Fn elf64_getshdr 463 Retrieve the ELF section header associated with an 464 .Vt Elf_Scn 465 descriptor. 466 .It Fn elf32_newehdr , Fn elf64_newehdr 467 Allocate an Executable Header in an ELF object. 468 .It Fn elf32_newphdr , Fn elf64_newphdr 469 Allocate or resize the Program Header Table in an ELF object. 470 .El 471 .It "Data Translation" 472 .Bl -tag -compact 473 .It Fn elf32_xlatetof , Fn elf64_xlatetof 474 Translate an ELF data structure from its native representation to its 475 file representation. 476 .It Fn elf32_xlatetom , Fn elf64_xlatetom 477 Translate an ELF data structure from its file representation to a 478 native representation. 479 .El 480 .It "Error Reporting" 481 .Bl -tag -compact 482 .It Fn elf_errno 483 Retrieve the current error. 484 .It Fn elf_errmsg 485 Retrieve a human readable description of the current error. 486 .El 487 .It "Initialization" 488 .Bl -tag -compact 489 .It Fn elf_begin 490 Opens an 491 .Xr ar 1 492 archive or ELF object given a file descriptor. 493 .It Fn elf_end 494 Close an ELF descriptor and release all its resources. 495 .It Fn elf_memory 496 Opens an 497 .Xr ar 1 498 archive or ELF object present in a memory arena. 499 .It Fn elf_version 500 Sets the operating version. 501 .El 502 .It "IO Control" 503 .Bl -tag -width ".Fn elf_setshstrndx" -compact 504 .It Fn elf_cntl 505 Manage the association between and ELF descriptor and its underlying file. 506 .It Fn elf_flagdata 507 Mark an 508 .Vt Elf_Data 509 descriptor as dirty. 510 .It Fn elf_flagehdr 511 Mark the ELF Executable Header in an ELF descriptor as dirty. 512 .It Fn elf_flagphdr 513 Mark the ELF Program Header Table in an ELF descriptor as dirty. 514 .It Fn elf_flagscn 515 Mark an 516 .Vt Elf_Scn 517 descriptor as dirty. 518 .It Fn elf_flagshdr 519 Mark an ELF Section Header as dirty. 520 .It Fn elf_setshstrndx 521 Set the index of the section name string table for the ELF object. 522 .It Fn elf_update 523 Recompute ELF object layout and optionally write the modified object 524 back to the underlying file. 525 .El 526 .It "Queries" 527 .Bl -tag -width ".Fn elf_getshstrndx" -compact 528 .It Fn elf32_checksum , Fn elf64_checkum 529 Compute checksum of an ELF object. 530 .It Fn elf_getident 531 Retrieve the identification bytes for an ELF object. 532 .It Fn elf_getshnum 533 Retrieve the number of sections in an ELF object. 534 .It Fn elf_getshstrndx 535 Retrieve the section index of the section name string table in 536 an ELF object. 537 .It Fn elf_hash 538 Compute the ELF hash value of a string. 539 .It Fn elf_kind 540 Query the kind of object associated with an ELF descriptor. 541 .It Fn elf32_fsize , Fn elf64_fsize 542 Return the size of the file representation of an ELF type. 543 .El 544 .El 545 .Ss Controlling ELF Object Layout 546 In the usual mode of operation, library will compute section 547 offsets and alignments based on the contents of an ELF descriptor's 548 sections without need for further intervention by the 549 application. 550 .Pp 551 However, if the application wishes to take complete charge of the 552 layout of the ELF file, it may set the 553 .Dv ELF_F_LAYOUT 554 flag on an ELF descriptor using 555 .Xr elf_flagelf 3 , 556 following which the library will use the data offsets and alignments 557 specified by the application when laying out the file. 558 Application control of file layout is described further in the 559 .Xr elf_update 3 560 manual page. 561 .Pp 562 Gaps in between sections will be filled with the fill character 563 set by function 564 .Fn elf_fill . 565 .Ss Error Handling 566 In case an error is encountered, these library functions set an 567 internal error number and signal the presence of the error by 568 returning an special return value. 569 The application can check the 570 current error number by calling 571 .Xr elf_errno 3 . 572 A human readable description of the recorded error is available by 573 calling 574 .Xr elf_errmsg 3 . 575 .Ss Memory Management Rules 576 The library keeps track of all 577 .Vt Elf_Scn 578 and 579 .Vt Elf_Data 580 descriptors associated with an ELF descriptor and recovers them 581 when the descriptor is closed using 582 .Xr elf_end 3 . 583 Thus the application must not call 584 .Xr free 3 585 on data structures allocated by the ELF library. 586 .Pp 587 Conversely the library will not 588 free data that it has not allocated. 589 As an example, an application may call 590 .Xr elf_newdata 3 591 to allocate a new 592 .Vt Elf_Data 593 descriptor and can set the 594 .Va d_off 595 member of the descriptor to point to a region of memory allocated 596 using 597 .Xr malloc 3 . 598 It is the applications responsibility to free this arena, though the 599 library will reclaim the space used by the 600 .Vt Elf_Data 601 descriptor itself. 602 .Sh SEE ALSO 603 .Xr gelf 3 , 604 .Xr elf 5 605 .Sh HISTORY 606 The original ELF(3) API was developed for Unix System V. 607 The current implementation of the ELF(3) API appeared in 608 .Fx 7.0 . 609 .Sh AUTHORS 610 The ELF library was written by 611 .An "Joseph Koshy" 612 .Aq jkoshy@FreeBSD.org .