1.\" $NetBSD: elf.5,v 1.15 2010/03/22 18:58:32 joerg Exp $ 2.\" 3.\" Copyright (c) 2001, 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This document is derived from work contributed to The NetBSD Foundation 7.\" by Antti Kantee. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE 22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd November 18, 2006 31.Dt ELF 5 32.Os 33.Sh NAME 34.Nm ELF 35.Nd executable and linking format 36.Sh SYNOPSIS 37.In elf.h 38.Sh DESCRIPTION 39Because of the flexible nature of ELF, the structures describing it are 40available both as 32bit and 64bit versions. This document uses the 32bit 41versions, refer to 42.In elf.h 43for the corresponding 64bit versions. 44.Pp 45The four main types of an ELF object file are: 46.Bl -tag -width "relocatable" 47.It executable 48A file suitable for execution. It contains the information required for 49creating a new process image. 50.It relocatable 51Contains the necessary information to be run through the link editor 52.Xr ld 1 53to create an executable or a shared library. 54.It shared 55The shared object contains necessary information which can be used by 56either the link editor 57.Xr ld 1 58at link time or by the dynamic loader 59.Xr ld.elf_so 1 60at run time. 61.It core 62A file which describes the virtual address space and register state 63of a process. Core files are typically used in conjunction with 64debuggers such as 65.Xr gdb 1 . 66.El 67.Pp 68ELF files have a dual nature. The toolchain, including tools such as the 69.Xr as 1 70and linker 71.Xr ld 1 , 72treats them as a set of sections described by their section headers. The system 73loader treats them as a set of segments described by the program headers. 74.Pp 75The general format of an ELF file is the following: The file starts with an 76ELF header. This is followed by a table of program headers (optional for 77relocatable and shared files). After this come the sections/segments. 78The file ends with a table of section headers (optional for executable 79files). 80.Pp 81A segment can be considered to consist of several sections. For example, 82all executable sections are typically packed into one loadable segment 83which is read-only and executable (see 84.Fa p_flags 85in the program header). This enables the system to map the entire file with 86just a few operations, one for each loadable segment, instead of doing 87numerous map operations for each section separately. 88.Pp 89Each file is described by the ELF header: 90.Bd -literal -offset indent 91typedef struct { 92 unsigned char e_ident[ELF_NIDENT]; 93 Elf32_Half e_type; 94 Elf32_Half e_machine; 95 Elf32_Word e_version; 96 Elf32_Addr e_entry; 97 Elf32_Off e_phoff; 98 Elf32_Off e_shoff; 99 Elf32_Word e_flags; 100 Elf32_Half e_ehsize; 101 Elf32_Half e_phentsize; 102 Elf32_Half e_phnum; 103 Elf32_Half e_shentsize; 104 Elf32_Half e_shnum; 105 Elf32_Half e_shstrndx; 106} Elf32_Ehdr; 107.Ed 108.Pp 109.Bl -tag -width "e_phentsize" 110.It Fa e_ident[] 111The array contains the following information in the indicated locations: 112.Bl -tag -width EI_ABIVERSION 113.It Dv EI_MAG0 114The elements ranging from 115.Dv EI_MAG0 116to 117.Dv EI_MAG3 118contain the ELF magic number: \\0177ELF 119.It Dv EI_CLASS 120Contains the address size of the binary, either 32 or 64bit. 121.It Dv EI_DATA 122byte order 123.It Dv EI_VERSION 124Contains the ELF header version. This is currently always set to 1. 125.It Dv EI_OSABI 126Contains the operating system ABI identification. Note that even though the 127definition 128.Dv ELFOSABI_NETBSD 129exists, 130.Nx 131uses 132.Dv ELFOSABI_SYSV 133here, since the 134.Nx 135ABI does not deviate from the standard. 136.It Dv EI_ABIVERSION 137ABI version. 138.El 139.It Fa e_type 140Contains the file type identification. It can be either 141.Dv ET_REL , 142.Dv ET_EXEC , 143.Dv ET_DYN , 144or 145.Dv ET_CORE 146for relocatable, executable, shared, or core, respectively. 147.It Fa e_machine 148Contains the machine type, e.g. SPARC, Alpha, MIPS, ... 149.It Fa e_entry 150The program entry point if the file is executable. 151.It Fa e_phoff 152The position of the program header table in the file or 0 if it doesn't exist. 153.It Fa e_shoff 154The position of the section header table in the file or 0 if it doesn't exist. 155.It Fa e_flags 156Contains processor-specific flags. For example, the SPARC port uses this 157space to specify what kind of memory store ordering is required. 158.It Fa e_ehsize 159The size of the ELF header. 160.It Fa e_phentsize 161The size of an entry in the program header table. All entries are the same 162size. 163.It Fa e_phnum 164The number of entries in the program header table, or 0 if none exists. 165.It Fa e_shentsize 166The size of an entry in the section header table. All entries are the same 167size. 168.It Fa e_shnum 169The number of entries in the section header table, or 0 if none exists. 170.It Fa e_shstrndx 171Contains the index number of the section which contains the section 172name strings. 173.El 174.Pp 175Each ELF section in turn is described by the section header: 176.Bd -literal -offset indent 177typedef struct { 178 Elf32_Word sh_name; 179 Elf32_Word sh_type; 180 Elf32_Word sh_flags; 181 Elf32_Addr sh_addr; 182 Elf32_Off sh_offset; 183 Elf32_Word sh_size; 184 Elf32_Word sh_link; 185 Elf32_Word sh_info; 186 Elf32_Word sh_addralign; 187 Elf32_Word sh_entsize; 188} Elf32_Shdr; 189.Ed 190.Pp 191.Bl -tag -width "sh_addralign" 192.It Fa sh_name 193Contains an index to the position in the section header string section where 194the name of the current section can be found. 195.It Fa sh_type 196Contains the section type indicator. The more important possible values are: 197.Bl -tag -width "SHT_PROGBITS" 198.It Dv SHT_NULL 199Section is inactive. The other fields contain undefined values. 200.It Dv SHT_PROGBITS 201Section contains program information. It can be for example code, data, 202or debugger information. 203.It Dv SHT_SYMTAB 204Section contains a symbol table. This section usually contains all the 205symbols and is intended for the regular link editor 206.Xr ld 1 . 207.It Dv SHT_STRTAB 208Section contains a string table. 209.It Dv SHT_RELA 210Section contains relocation information with an explicit addend. 211.It Dv SHT_HASH 212Section contains a symbol hash table. 213.It Dv SHT_DYNAMIC 214Section contains dynamic linking information. 215.It Dv SHT_NOTE 216Section contains some special information. The format can be e.g. 217vendor-specific. 218.It Dv SHT_NOBITS 219Sections contains information similar to 220.Dv SHT_PROGBITS , 221but takes up no space in the file. This can be used for e.g. bss. 222.It Dv SHT_REL 223Section contains relocation information without an explicit addend. 224.It Dv SHT_SHLIB 225This section type is reserved but has unspecified semantics. 226.It Dv SHT_DYNSYM 227Section contains a symbol table. This symbol table is intended for the 228dynamic linker, and is kept as small as possible to conserve space, since 229it must be loaded to memory at run time. 230.El 231.It Fa sh_flags 232Contains the section flags, which can have the following values or any 233combination of them: 234.Bl -tag -width SHF_EXECINSTR 235.It Dv SHF_WRITE 236Section is writable after it has been loaded. 237.It Dv SHF_ALLOC 238Section will occupy memory at run time. 239.It Dv SHF_EXECINSTR 240Section contains executable machine instructions. 241.El 242.It Fa sh_addr 243Address to where the section will be loaded, or 0 if this section does not 244reside in memory at run time. 245.It Fa sh_offset 246The byte offset from the beginning of the file to the beginning of this 247section. If the section is of type 248.Dv SHT_NOBITS , 249this field specifies the conceptual placement in the file. 250.It Fa sh_size 251The size of the section in the file for all types except 252.Dv SHT_NOBITS . 253For that type the value may differ from zero, but the section will still 254always take up no space from the file. 255.It Fa sh_link 256Contains an index to the section header table. The interpretation depends 257on the section type as follows: 258.Pp 259.Bl -tag -compact -width SHT_DYNAMIC 260.It Dv SHT_REL 261.It Dv SHT_RELA 262Section index of the associated symbol table. 263.Pp 264.It Dv SHT_SYMTAB 265.It Dv SHT_DYNSYM 266Section index of the associated string table. 267.Pp 268.It Dv SHT_HASH 269Section index of the symbol table to which the hash table applies. 270.Pp 271.It Dv SHT_DYNAMIC 272Section index of of the string table by which entries in this section are used. 273.El 274.It Fa sh_info 275Contains extra information. The interpretation depends on the type as 276follows: 277.Pp 278.Bl -tag -compact -width SHT_DYNSYM 279.It Dv SHT_REL 280.It Dv SHT_RELA 281Section index of the section to which the relocation information applies. 282.Pp 283.It Dv SHT_SYMTAB 284.It Dv SHT_DYNSYM 285Contains a value one greater that the last local symbol table index. 286.El 287.It Fa sh_addralign 288Marks the section alignment requirement. If, for example, the section contains 289a doubleword, the entire section must be doubleword aligned to ensure proper 290alignment. Only 0 and integral powers of two are allowed. Values 0 and 1 291denote that the section has no alignment. 292.It Fa sh_entsize 293Contains the entry size of an element for sections which are constructed 294of a table of fixed-size entries. If the section does not hold a table of 295fixed-size entries, this value is 0. 296.El 297.Pp 298Every executable object must contain a program header. The program header 299contains information necessary in constructing a process image. 300.Bd -literal -offset indent 301typedef struct { 302 Elf32_Word p_type; 303 Elf32_Off p_offset; 304 Elf32_Addr p_vaddr; 305 Elf32_Addr p_paddr; 306 Elf32_Word p_filesz; 307 Elf32_Word p_memsz; 308 Elf32_Word p_flags; 309 Elf32_Word p_align; 310} Elf32_Phdr; 311.Ed 312.Pp 313.Bl -tag -width p_offset 314.It Fa p_type 315Contains the segment type indicator. The possible values are: 316.Bl -tag -width PT_DYNAMIC 317.It Dv PT_NULL 318Segment is inactive. The other fields contain undefined values. 319.It Dv PT_LOAD 320Segment is loadable. It is loaded to the address described by 321.Fa p_vaddr . 322If 323.Fa p_memsz 324is greater than 325.Fa p_filesz , 326the memory range from 327.Po Fa p_vaddr 328+ 329.Fa p_filesz Pc 330to 331.Po Fa p_vaddr 332+ 333.Fa p_memsz Pc 334is zero-filled when the segment is loaded. 335.Fa p_filesz 336can not be greater than 337.Fa p_memsz . 338Segments of this type are sorted in the header table by 339.Fa p_vaddr 340in ascending order. 341.It Dv PT_DYNAMIC 342Segment contains dynamic linking information. 343.It Dv PT_INTERP 344Segment contains a null-terminated path name to the interpreter. This segment 345may be present only once in a file, and it must appear before any loadable 346segments. This field will most likely contain the ELF dynamic loader: 347.Pa /libexec/ld.elf_so 348.It Dv PT_NOTE 349Segment contains some special information. Format can be e.g. vendor-specific. 350.It Dv PT_SHLIB 351This segment type is reserved but has unspecified semantics. Programs 352which contain a segment of this type do not conform to the ABI, and must 353indicate this by setting the appropriate ABI in the ELF header 354.Dv EI_OSABI 355field. 356.It Dv PT_PHDR 357The values in a program header of this type specify the characteristics 358of the program header table itself. For example, the 359.Fa p_vaddr 360field specifies the program header table location in memory once the 361program is loaded. This field may not occur more than once, may occur only 362if the program header table is part of the file memory image, and must 363come before any loadable segments. 364.El 365.It Fa p_offset 366Contains the byte offset from the beginning of the file to the beginning 367of this segment. 368.It Fa p_vaddr 369Contains the virtual memory address to which this segment is loaded. 370.It Fa p_paddr 371Contains the physical address to which this segment is loaded. This value 372is usually ignored, but may be used while bootstrapping or in embedded 373systems. 374.It Fa p_filesz 375Contains the number of bytes this segment occupies in the file image. 376.It Fa p_memsz 377Contains the number of bytes this segment occupies in the memory image. 378.It Fa p_flags 379Contains the segment flags, which specify the permissions for the segment 380after it has been loaded. The following values or any combination of them 381is acceptable: 382.Bl -tag -width PF_R 383.It Dv PF_R 384Segment can be read. 385.It Dv PF_W 386Segment can be written. 387.It Dv PF_X 388Segment is executable. 389.El 390.It Fa p_align 391Contains the segment alignment. Acceptable values are 0 and 1 for no alignment, 392and integral powers of two. 393.Fa p_vaddr 394should equal 395.Fa p_offset 396modulo 397.Fa p_align . 398.El 399.Sh SEE ALSO 400.Xr as 1 , 401.Xr gdb 1 , 402.Xr ld 1 , 403.Xr ld.elf_so 1 , 404.Xr execve 2 , 405.Xr nlist 3 , 406.Xr a.out 5 , 407.Xr core 5 , 408.Xr link 5 , 409.Xr stab 5 410.Sh HISTORY 411The ELF object file format first appeared in 412.At V . 413