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