| blob | 2ec7c64b0a8872c4097410e33c1d0811ab5a237c |
1 .\" $NetBSD: elf.5,v 1.13 2006/11/18 14:32:14 pooka 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
39 Because of the flexible nature of ELF, the structures describing it are
40 available both as 32bit and 64bit versions. This document uses the 32bit
41 versions, refer to
42 .Aq Pa elf.h
43 for the corresponding 64bit versions.
44 .Pp
45 The four main types of an ELF object file are:
46 .Bl -tag -width "relocatable"
47 .It executable
48 A file suitable for execution. It contains the information required for
49 creating a new process image.
50 .It relocatable
51 Contains the necessary information to be run through the link editor
52 .Xr ld 1
53 to create an executable or a shared library.
54 .It shared
55 The shared object contains necessary information which can be used by
56 either the link editor
57 .Xr ld 1
58 at link time or by the dynamic loader
59 .Xr ld.elf_so 1
60 at run time.
61 .It core
62 A file which describes the virtual address space and register state
63 of a process. Core files are typically used in conjunction with
64 debuggers such as
65 .Xr gdb 1 .
66 .El
67 .Pp
68 ELF files have a dual nature. The toolchain, including tools such as the
69 .Xr as 1
70 and linker
71 .Xr ld 1 ,
72 treats them as a set of sections described by their section headers. The system
73 loader treats them as a set of segments described by the program headers.
74 .Pp
75 The general format of an ELF file is the following: The file starts with an
76 ELF header. This is followed by a table of program headers (optional for
77 relocatable and shared files). After this come the sections/segments.
78 The file ends with a table of section headers (optional for executable
79 files).
80 .Pp
81 A segment can be considered to consist of several sections. For example,
82 all executable sections are typically packed into one loadable segment
83 which is read-only and executable (see
84 .Fa p_flags
85 in the program header). This enables the system to map the entire file with
86 just a few operations, one for each loadable segment, instead of doing
87 numerous map operations for each section separately.
88 .Pp
89 Each file is described by the ELF header:
90 .Bd -literal -offset indent
91 typedef 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[]
111 The array contains the following information in the indicated locations:
112 .Bl -tag -width EI_ABIVERSION
113 .It Dv EI_MAG0
114 The elements ranging from
115 .Dv EI_MAG0
116 to
117 .Dv EI_MAG3
118 contain the ELF magic number: \\0177ELF
119 .It Dv EI_CLASS
120 Contains the address size of the binary, either 32 or 64bit.
121 .It Dv EI_DATA
122 byte order
123 .It Dv EI_VERSION
124 Contains the ELF header version. This is currently always set to 1.
125 .It Dv EI_OSABI
126 Contains the operating system ABI identification. Note that even though the
127 definition
128 .Dv ELFOSABI_NETBSD
129 exists,
130 .Nx
131 uses
132 .Dv ELFOSABI_SYSV
133 here, since the
134 .Nx
135 ABI does not deviate from the standard.
136 .It Dv EI_ABIVERSION
137 ABI version.
138 .El
139 .It Fa e_type
140 Contains the file type identification. It can be either
141 .Dv ET_REL ,
142 .Dv ET_EXEC ,
143 .Dv ET_DYN ,
144 or
145 .Dv ET_CORE
146 for relocatable, executable, shared, or core, respectively.
147 .It Fa e_machine
148 Contains the machine type, e.g. SPARC, Alpha, MIPS, ...
149 .It Fa e_entry
150 The program entry point if the file is executable.
151 .It Fa e_phoff
152 The position of the program header table in the file or 0 if it doesn't exist.
153 .It Fa e_shoff
154 The position of the section header table in the file or 0 if it doesn't exist.
155 .It Fa e_flags
156 Contains processor-specific flags. For example, the SPARC port uses this
157 space to specify what kind of memory store ordering is required.
158 .It Fa e_ehsize
159 The size of the ELF header.
160 .It Fa e_phentsize
161 The size of an entry in the program header table. All entries are the same
162 size.
163 .It Fa e_phnum
164 The number of entries in the program header table, or 0 if none exists.
165 .It Fa e_shentsize
166 The size of an entry in the section header table. All entries are the same
167 size.
168 .It Fa e_shnum
169 The number of entries in the section header table, or 0 if none exists.
170 .It Fa e_shstrndx
171 Contains the index number of the section which contains the section
172 name strings.
173 .El
174 .Pp
175 Each ELF section in turn is described by the section header:
176 .Bd -literal -offset indent
177 typedef 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
193 Contains an index to the position in the section header string section where
194 the name of the current section can be found.
195 .It Fa sh_type
196 Contains the section type indicator. The more important possible values are:
197 .Bl -tag -width "SHT_PROGBITS"
198 .It Dv SHT_NULL
199 Section is inactive. The other fields contain undefined values.
200 .It Dv SHT_PROGBITS
201 Section contains program information. It can be for example code, data,
202 or debugger information.
203 .It Dv SHT_SYMTAB
204 Section contains a symbol table. This section usually contains all the
205 symbols and is intended for the regular link editor
206 .Xr ld 1 .
207 .It Dv SHT_STRTAB
208 Section contains a string table.
209 .It Dv SHT_RELA
210 Section contains relocation information with an explicit addend.
211 .It Dv SHT_HASH
212 Section contains a symbol hash table.
213 .It Dv SHT_DYNAMIC
214 Section contains dynamic linking information.
215 .It Dv SHT_NOTE
216 Section contains some special information. The format can be e.g.
217 vendor-specific.
218 .It Dv SHT_NOBITS
219 Sections contains information similar to
220 .Dv SHT_PROGBITS ,
221 but takes up no space in the file. This can be used for e.g. bss.
222 .It Dv SHT_REL
223 Section contains relocation information without an explicit addend.
224 .It Dv SHT_SHLIB
225 This section type is reserved but has unspecified semantics.
226 .It Dv SHT_DYNSYM
227 Section contains a symbol table. This symbol table is intended for the
228 dynamic linker, and is kept as small as possible to conserve space, since
229 it must be loaded to memory at run time.
230 .El
231 .It Fa sh_flags
232 Contains the section flags, which can have the following values or any
233 combination of them:
234 .Bl -tag -width SHF_EXECINSTR
235 .It Dv SHF_WRITE
236 Section is writable after it has been loaded.
237 .It Dv SHF_ALLOC
238 Section will occupy memory at run time.
239 .It Dv SHF_EXECINSTR
240 Section contains executable machine instructions.
241 .El
242 .It Fa sh_addr
243 Address to where the section will be loaded, or 0 if this section does not
244 reside in memory at run time.
245 .It Fa sh_offset
246 The byte offset from the beginning of the file to the beginning of this
247 section. If the section is of type
248 .Dv SHT_NOBITS ,
249 this field specifies the conceptual placement in the file.
250 .It Fa sh_size
251 The size of the section in the file for all types except
252 .Dv SHT_NOBITS .
253 For that type the value may differ from zero, but the section will still
254 always take up no space from the file.
255 .It Fa sh_link
256 Contains an index to the section header table. The interpretation depends
257 on the section type as follows:
258 .Pp
259 .Bl -tag -compact -width SHT_DYNAMIC
260 .It Dv SHT_REL
261 .It Dv SHT_RELA
262 Section index of the associated symbol table.
263 .Pp
264 .It Dv SHT_SYMTAB
265 .It Dv SHT_DYNSYM
266 Section index of the associated string table.
267 .Pp
268 .It Dv SHT_HASH
269 Section index of the symbol table to which the hash table applies.
270 .Pp
271 .It Dv SHT_DYNAMIC
272 Section index of of the string table by which entries in this section are used.
273 .El
274 .It Fa sh_info
275 Contains extra information. The interpretation depends on the type as
276 follows:
277 .Pp
278 .Bl -tag -compact -width SHT_DYNSYM
279 .It Dv SHT_REL
280 .It Dv SHT_RELA
281 Section index of the section to which the relocation information applies.
282 .Pp
283 .It Dv SHT_SYMTAB
284 .It Dv SHT_DYNSYM
285 Contains a value one greater that the last local symbol table index.
286 .El
287 .It Fa sh_addralign
288 Marks the section alignment requirement. If, for example, the section contains
289 a doubleword, the entire section must be doubleword aligned to ensure proper
290 alignment. Only 0 and integral powers of two are allowed. Values 0 and 1
291 denote that the section has no alignment.
292 .It Fa sh_entsize
293 Contains the entry size of an element for sections which are constructed
294 of a table of fixed-size entries. If the section does not hold a table of
295 fixed-size entries, this value is 0.
296 .El
297 .Pp
298 Every executable object must contain a program header. The program header
299 contains information necessary in constructing a process image.
300 .Bd -literal -offset indent
301 typedef 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
315 Contains the segment type indicator. The possible values are:
316 .Bl -tag -width PT_DYNAMIC
317 .It Dv PT_NULL
318 Segment is inactive. The other fields contain undefined values.
319 .It Dv PT_LOAD
320 Segment is loadable. It is loaded to the address described by
321 .Fa p_vaddr .
322 If
323 .Fa p_memsz
324 is greater than
325 .Fa p_filesz ,
326 the memory range from
327 .Po Fa p_vaddr
328 +
329 .Fa p_filesz Pc
330 to
331 .Po Fa p_vaddr
332 +
333 .Fa p_memsz Pc
334 is zero-filled when the segment is loaded.
335 .Fa p_filesz
336 can not be greater than
337 .Fa p_memsz .
338 Segments of this type are sorted in the header table by
339 .Fa p_vaddr
340 in ascending order.
341 .It Dv PT_DYNAMIC
342 Segment contains dynamic linking information.
343 .It Dv PT_INTERP
344 Segment contains a null-terminated path name to the interpreter. This segment
345 may be present only once in a file, and it must appear before any loadable
346 segments. This field will most likely contain the ELF dynamic loader:
347 .Pa /libexec/ld.elf_so
348 .It Dv PT_NOTE
349 Segment contains some special information. Format can be e.g. vendor-specific.
350 .It Dv PT_SHLIB
351 This segment type is reserved but has unspecified semantics. Programs
352 which contain a segment of this type do not conform to the ABI, and must
353 indicate this by setting the appropriate ABI in the ELF header
354 .Dv EI_OSABI
355 field.
356 .It Dv PT_PHDR
357 The values in a program header of this type specify the characteristics
358 of the program header table itself. For example, the
359 .Fa p_vaddr
360 field specifies the program header table location in memory once the
361 program is loaded. This field may not occur more than once, may occur only
362 if the program header table is part of the file memory image, and must
363 come before any loadable segments.
364 .El
365 .It Fa p_offset
366 Contains the byte offset from the beginning of the file to the beginning
367 of this segment.
368 .It Fa p_vaddr
369 Contains the virtual memory address to which this segment is loaded.
370 .It Fa p_paddr
371 Contains the physical address to which this segment is loaded. This value
372 is usually ignored, but may be used while bootstrapping or in embedded
373 systems.
374 .It Fa p_filesz
375 Contains the number of bytes this segment occupies in the file image.
376 .It Fa p_memsz
377 Contains the number of bytes this segment occupies in the memory image.
378 .It Fa p_flags
379 Contains the segment flags, which specify the permissions for the segment
380 after it has been loaded. The following values or any combination of them
381 is acceptable:
382 .Bl -tag -width PF_R
383 .It Dv PF_R
384 Segment can be read.
385 .It Dv PF_W
386 Segment can be written.
387 .It Dv PF_X
388 Segment is executable.
389 .El
390 .It Fa p_align
391 Contains the segment alignment. Acceptable values are 0 and 1 for no alignment,
392 and integral powers of two.
393 .Fa p_vaddr
394 should equal
395 .Fa p_offset
396 modulo
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
411 The ELF object file format first appeared in
412 .At V .