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