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