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