share/man/man5/elf.5

   1 .\"Copyright (c) 1999 Jeroen Ruigrok van der Werven
   2 .\"All rights reserved.
   3 .\"
   4 .\"Redistribution and use in source and binary forms, with or without
   5 .\"modification, are permitted provided that the following conditions
   6 .\"are met:
   7 .\"1. Redistributions of source code must retain the above copyright
   8 .\"   notice, this list of conditions and the following disclaimer.
   9 .\"2. Redistributions in binary form must reproduce the above copyright
  10 .\"   notice, this list of conditions and the following disclaimer in the
  11 .\"   documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\"THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\"ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\"IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\"ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\"FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\"DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\"OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\"HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\"LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\"OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\"SUCH DAMAGE.
  24 .\"
  25 .\"     $FreeBSD: src/share/man/man5/elf.5,v 1.6.2.8 2001/12/17 11:30:13 ru Exp $
  26 .\"     $DragonFly: src/share/man/man5/elf.5,v 1.11 2008/05/02 02:05:06 swildner Exp $
  27 .\"
  28 .Dd February 9, 2008
  29 .Dt ELF 5
  30 .Os
  31 .Sh NAME
  32 .Nm elf
  33 .Nd format of ELF executable binary files
  34 .Sh SYNOPSIS
  35 .In elf.h
  36 .Sh DESCRIPTION
  37 The header file
  38 .In elf.h
  39 defines the format of ELF executable binary files.
  40 Amongst these files are
  41 normal executable files, relocatable object files, core files and shared
  42 libraries.
  43 .Pp
  44 An executable file using the ELF file format consists of an ELF header,
  45 followed by a program header table or a section header table, or both.
  46 The ELF header is always at offset zero of the file.
  47 The program header
  48 table and the section header table's offset in the file are defined in the
  49 ELF header.
  50 The two tables describe the rest of the particularities of
  51 the file.
  52 .Pp
  53 Applications which wish to process ELF binary files for their native
  54 architecture only should include
  55 .In elf.h
  56 in their source code.
  57 These applications should need to refer to
  58 all the types and structures by their generic names
  59 .Dq Elf_xxx
  60 and to the macros by
  61 .Dq ELF_xxx .
  62 Applications written this way can be compiled on any architecture,
  63 regardless whether the host is 32-bit or 64-bit.
  64 .Pp
  65 Should an application need to process ELF files of an unknown
  66 architecture then the application needs to include both
  67 .In sys/elf32.h
  68 and
  69 .In sys/elf64.h
  70 instead of
  71 .In elf.h .
  72 Furthermore, all types and structures need to be identified by either
  73 .Dq Elf32_xxx
  74 or
  75 .Dq Elf64_xxx .
  76 The macros need to be identified by
  77 .Dq ELF32_xxx
  78 or
  79 .Dq ELF64_xxx .
  80 .Pp
  81 Whatever the system's architecture is, it will always include
  82 .In sys/elf_common.h
  83 as well as
  84 .In sys/elf_generic.h .
  85 .Pp
  86 These header files describe the above mentioned headers as C structures
  87 and also include structures for dynamic sections, relocation sections and
  88 symbol tables.
  89 .Pp
  90 The following types are being used for 32-bit architectures:
  91 .Bd -literal -offset indent
  92 Elf32_Addr      Unsigned 32-bit program address
  93 Elf32_Half      Unsigned 16-bit field
  94 Elf32_Off       Unsigned 32-bit file offset
  95 Elf32_Sword     Signed 32-bit field or integer
  96 Elf32_Word      Unsigned 32-bit field or integer
  97 Elf32_Size      Unsigned object size
  98 .Ed
  99 .Pp
 100 For 64-bit architectures we have the following types:
 101 .Bd -literal -offset indent
 102 Elf64_Addr      Unsigned 64-bit program address
 103 Elf64_Half      Unsigned 16-bit field
 104 Elf64_Lword     Unsigned 64-bit field
 105 Elf64_Off       Unsigned 64-bit file offset
 106 Elf64_Sword     Signed 32-bit field
 107 Elf64_Sxword    Signed 64-bit field or integer
 108 Elf64_Word      Unsigned 32-bit field
 109 Elf64_Xword     Unsigned 64-bit field or integer
 110 Elf64_Size      Unsigned object size
 111 Elf64_Quarter   Unsigned quarterword field
 112 .Ed
 113 .Pp
 114 All data structures that the file format defines follow the
 115 .Dq natural
 116 size and alignment guidelines for the relevant class.
 117 If necessary,
 118 data structures contain explicit padding to ensure 4-byte alignment
 119 for 4-byte objects, to force structure sizes to a multiple of 4, etc.
 120 .Pp
 121 The ELF header is described by the type Elf32_Ehdr or Elf64_Ehdr:
 122 .Bd -literal -offset indent
 123 typedef struct {
 124         unsigned char   e_ident[EI_NIDENT];
 125         Elf32_Half      e_type;
 126         Elf32_Half      e_machine;
 127         Elf32_Word      e_version;
 128         Elf32_Addr      e_entry;
 129         Elf32_Off       e_phoff;
 130         Elf32_Off       e_shoff;
 131         Elf32_Word      e_flags;
 132         Elf32_Half      e_ehsize;
 133         Elf32_Half      e_phentsize;
 134         Elf32_Half      e_phnum;
 135         Elf32_Half      e_shentsize;
 136         Elf32_Half      e_shnum;
 137         Elf32_Half      e_shstrndx;
 138 } Elf32_Ehdr;
 139 .Ed
 140 .Bd -literal -offset indent
 141 typedef struct {
 142         unsigned char   e_ident[EI_NIDENT];
 143         Elf64_Quarter   e_type;
 144         Elf64_Quarter   e_machine;
 145         Elf64_Half      e_version;
 146         Elf64_Addr      e_entry;
 147         Elf64_Off       e_phoff;
 148         Elf64_Off       e_shoff;
 149         Elf64_Half      e_flags;
 150         Elf64_Quarter   e_ehsize;
 151         Elf64_Quarter   e_phentsize;
 152         Elf64_Quarter   e_phnum;
 153         Elf64_Quarter   e_shentsize;
 154         Elf64_Quarter   e_shnum;
 155         Elf64_Quarter   e_shstrndx;
 156 } Elf64_Ehdr;
 157 .Ed
 158 .Pp
 159 The fields have the following meanings:
 160 .Pp
 161 .Bl -tag -width ".Fa e_phentsize" -compact -offset indent
 162 .It Fa e_ident
 163 This array of bytes specifies to interpret the file,
 164 independent of the processor or the file's remaining contents.
 165 Within this array everything is named by macros, which start with
 166 the prefix
 167 .Sy EI_
 168 and may contain values which start with the prefix
 169 .Sy ELF .
 170 The following macros are defined:
 171 .Pp
 172 .Bl -tag -width ".Dv EI_ABIVERSION" -compact
 173 .It Dv EI_MAG0
 174 The first byte of the magic number.
 175 It must be filled with
 176 .Sy ELFMAG0 .
 177 .It Dv EI_MAG1
 178 The second byte of the magic number.
 179 It must be filled with
 180 .Sy ELFMAG1 .
 181 .It Dv EI_MAG2
 182 The third byte of the magic number.
 183 It must be filled with
 184 .Sy ELFMAG2 .
 185 .It Dv EI_MAG3
 186 The fourth byte of the magic number.
 187 It must be filled with
 188 .Sy ELFMAG3 .
 189 .It Dv EI_CLASS
 190 The fifth byte identifies the architecture for this binary:
 191 .Pp
 192 .Bl -tag -width ".Dv ELFCLASSNONE" -compact
 193 .It Dv ELFCLASSNONE
 194 This class is invalid.
 195 .It Dv ELFCLASS32
 196 This defines the 32-bit architecture.
 197 It supports machines with files
 198 and virtual address spaces up to 4 Gigabytes.
 199 .It Dv ELFCLASS64
 200 This defines the 64-bit architecture.
 201 .El
 202 .It Dv EI_DATA
 203 The sixth byte specifies the data encoding of the processor-specific
 204 data in the file.
 205 Currently these encodings are supported:
 206 .Pp
 207 .Bl -tag -width ".Dv ELFDATA2LSB" -compact
 208 .It Dv ELFDATANONE
 209 Unknown data format.
 210 .It Dv ELFDATA2LSB
 211 Two's complement, little-endian.
 212 .It Dv ELFDATA2MSB
 213 Two's complement, big-endian.
 214 .El
 215 .It Dv EI_VERSION
 216 The version number of the ELF specification:
 217 .Pp
 218 .Bl -tag -width ".Dv EV_CURRENT" -compact
 219 .It Dv EV_NONE
 220 Invalid version.
 221 .It Dv EV_CURRENT
 222 Current version.
 223 .El
 224 .It Dv EI_OSABI
 225 This byte identifies the operating system
 226 and ABI to which the object is targeted.
 227 Some fields in other ELF structures have flags
 228 and values that have platform specific meanings;
 229 the interpretation of those fields is determined by the value of this byte.
 230 The following values are currently defined:
 231 .Pp
 232 .Bl -tag -width ".Dv ELFOSABI_STANDALONE" -compact
 233 .It Dv ELFOSABI_SYSV
 234 .At V
 235 ABI.
 236 .It Dv ELFOSABI_HPUX
 237 HP-UX operating system ABI.
 238 .It Dv ELFOSABI_NETBSD
 239 .Nx
 240 operating system ABI.
 241 .It Dv ELFOSABI_LINUX
 242 GNU/Linux operating system ABI.
 243 .It Dv ELFOSABI_HURD
 244 GNU/Hurd operating system ABI.
 245 .It Dv ELFOSABI_86OPEN
 246 86Open Common IA32 ABI.
 247 .It Dv ELFOSABI_SOLARIS
 248 Solaris operating system ABI.
 249 .It Dv ELFOSABI_MONTEREY
 250 Monterey project ABI.
 251 .It Dv ELFOSABI_IRIX
 252 IRIX operating system ABI.
 253 .It Dv ELFOSABI_FREEBSD
 254 .Fx
 255 operating system ABI.
 256 .It Dv ELFOSABI_TRU64
 257 TRU64
 258 .Ux
 259 operating system ABI.
 260 .It Dv ELFOSABI_ARM
 261 ARM architecture ABI.
 262 .It Dv ELFOSABI_STANDALONE
 263 Standalone (embedded) ABI.
 264 .El
 265 .It Dv EI_ABIVERSION
 266 This byte identifies the version of the ABI
 267 to which the object is targeted.
 268 This field is used to distinguish among incompatible versions of an ABI.
 269 The interpretation of this version number
 270 is dependent on the ABI identified by the
 271 .Dv EI_OSABI
 272 field.
 273 Applications conforming to this specification use the value 0.
 274 .It Dv EI_PAD
 275 Start of padding.
 276 These bytes are reserved and set to zero.
 277 Programs
 278 which read them should ignore them.
 279 The value for EI_PAD will change in
 280 the future if currently unused bytes are given meanings.
 281 .It Dv EI_NIDENT
 282 The size of the
 283 .Fa e_ident
 284 array.
 285 .El
 286 .Pp
 287 .It Fa e_type
 288 This member of the structure identifies the object file type:
 289 .Pp
 290 .Bl -tag -width ".Dv ET_NONE" -compact
 291 .It Dv ET_NONE
 292 An unknown type.
 293 .It Dv ET_REL
 294 A relocatable file.
 295 .It Dv ET_EXEC
 296 An executable file.
 297 .It Dv ET_DYN
 298 A shared object.
 299 .It Dv ET_CORE
 300 A core file.
 301 .El
 302 .Pp
 303 .It Fa e_machine
 304 This member specifies the required architecture for an individual file:
 305 .Pp
 306 .Bl -tag -width ".Dv EM_MIPS_RS4_BE" -compact
 307 .It Dv EM_NONE
 308 An unknown machine.
 309 .It Dv EM_M32
 310 AT&T WE 32100.
 311 .It Dv EM_SPARC
 312 Sun Microsystems SPARC.
 313 .It Dv EM_386
 314 Intel 80386.
 315 .It Dv EM_68K
 316 Motorola 68000.
 317 .It Dv EM_88K
 318 Motorola 88000.
 319 .It Dv EM_860
 320 Intel 80860.
 321 .It Dv EM_MIPS
 322 MIPS RS3000 (big-endian only).
 323 .It Dv EM_MIPS_RS4_BE
 324 MIPS RS4000 (big-endian only).
 325 .It Dv EM_SPARC64
 326 SPARC v9 64-bit unofficial.
 327 .It Dv EM_PARISC
 328 HPPA.
 329 .It Dv EM_PPC
 330 PowerPC.
 331 .It Dv EM_ALPHA
 332 Compaq [DEC] Alpha.
 333 .El
 334 .Pp
 335 .It Fa e_version
 336 This member identifies the file version:
 337 .Pp
 338 .Bl -tag -width ".Dv EV_CURRENT" -compact
 339 .It Dv EV_NONE
 340 Invalid version
 341 .It Dv EV_CURRENT
 342 Current version
 343 .El
 344 .It Fa e_entry
 345 This member gives the virtual address to which the system first transfers
 346 control, thus starting the process.
 347 If the file has no associated entry
 348 point, this member holds zero.
 349 .It Fa e_phoff
 350 This member holds the program header table's file offset in bytes.
 351 If
 352 the file has no program header table, this member holds zero.
 353 .It Fa e_shoff
 354 This member holds the section header table's file offset in bytes.
 355 If the
 356 file has no section header table this member holds zero.
 357 .It Fa e_flags
 358 This member holds processor-specific flags associated with the file.
 359 Flag names take the form EF_`machine_flag'.
 360 Currently no flags have been defined.
 361 .It Fa e_ehsize
 362 This member holds the ELF header's size in bytes.
 363 .It Fa e_phentsize
 364 This member holds the size in bytes of one entry in the file's program header
 365 table; all entries are the same size.
 366 .It Fa e_phnum
 367 This member holds the number of entries in the program header
 368 table.
 369 Thus the product of
 370 .Fa e_phentsize
 371 and
 372 .Fa e_phnum
 373 gives the table's size
 374 in bytes.
 375 If a file has no program header,
 376 .Fa e_phnum
 377 holds the value zero.
 378 .It Fa e_shentsize
 379 This member holds a sections header's size in bytes.
 380 A section header is one
 381 entry in the section header table; all entries are the same size.
 382 .It Fa e_shnum
 383 This member holds the number of entries in the section header table.
 384 Thus
 385 the product of
 386 .Fa e_shentsize
 387 and
 388 .Fa e_shnum
 389 gives the section header table's size in bytes.
 390 If a file has no section
 391 header table,
 392 .Fa e_shnum
 393 holds the value of zero.
 394 .It Fa e_shstrndx
 395 This member holds the section header table index of the entry associated
 396 with the section name string table.
 397 If the file has no section name string
 398 table, this member holds the value
 399 .Dv SHN_UNDEF .
 400 .Pp
 401 .Bl -tag -width ".Dv SHN_LORESERVE" -compact
 402 .It Dv SHN_UNDEF
 403 This value marks an undefined, missing, irrelevant, or otherwise meaningless
 404 section reference.
 405 For example, a symbol
 406 .Dq defined
 407 relative to section number
 408 .Dv SHN_UNDEF
 409 is an undefined symbol.
 410 .It Dv SHN_LORESERVE
 411 This value specifies the lower bound of the range of reserved indexes.
 412 .It Dv SHN_LOPROC
 413 This value up to and including
 414 .Dv SHN_HIPROC
 415 are reserved for processor-specific semantics.
 416 .It Dv SHN_HIPROC
 417 This value down to and including
 418 .Dv SHN_LOPROC
 419 are reserved for processor-specific semantics.
 420 .It Dv SHN_ABS
 421 This value specifies absolute values for the corresponding reference.
 422 For
 423 example, symbols defined relative to section number
 424 .Dv SHN_ABS
 425 have absolute values and are not affected by relocation.
 426 .It Dv SHN_COMMON
 427 Symbols defined relative to this section are common symbols, such as Fortran
 428 COMMON or unallocated C external variables.
 429 .It Dv SHN_HIRESERVE
 430 This value specifies the upper bound of the range of the range of reserved
 431 indices between
 432 .Dv SHN_LORESERVE
 433 and
 434 .Dv SHN_HIRESERVE ,
 435 inclusive; the values do
 436 not reference the section header table.
 437 That is, the section header table
 438 does
 439 .Em not
 440 contain entries for the reserved indices.
 441 .El
 442 .El
 443 .Pp
 444 An executable or shared object file's program header table is an array of
 445 structures, each describing a segment or other information the system needs
 446 to prepare the program for execution.
 447 An object file
 448 .Em segment
 449 contains one or more
 450 .Em sections .
 451 Program headers are meaningful only for executable and shared object files.
 452 A file specifies its own program header size with the ELF header's
 453 .Fa e_phentsize
 454 and
 455 .Fa e_phnum
 456 members.
 457 As with the Elf executable header, the program header
 458 also has different versions depending on the architecture:
 459 .Bd -literal -offset indent
 460 typedef struct {
 461         Elf32_Word      p_type;
 462         Elf32_Off       p_offset;
 463         Elf32_Addr      p_vaddr;
 464         Elf32_Addr      p_paddr;
 465         Elf32_Size      p_filesz;
 466         Elf32_Size      p_memsz;
 467         Elf32_Word      p_flags;
 468         Elf32_Size      p_align;
 469 } Elf32_Phdr;
 470 .Ed
 471 .Bd -literal -offset indent
 472 typedef struct {
 473         Elf64_Half      p_type;
 474         Elf64_Half      p_flags;
 475         Elf64_Off       p_offset;
 476         Elf64_Addr      p_vaddr;
 477         Elf64_Addr      p_paddr;
 478         Elf64_Size      p_filesz;
 479         Elf64_Size      p_memsz;
 480         Elf64_Size      p_align;
 481 } Elf64_Phdr;
 482 .Ed
 483 .Pp
 484 The main difference between the 32-bit and the 64-bit program header lies
 485 only in the location of a
 486 .Fa p_flags
 487 member in the total struct.
 488 .Pp
 489 .Bl -tag -width ".Fa p_offset" -compact -offset indent
 490 .It Fa p_type
 491 This member of the
 492 .Vt Phdr
 493 struct tells what kind of segment this array
 494 element describes or how to interpret the array element's information.
 495 .Pp
 496 .Bl -tag -width ".Dv PT_DYNAMIC" -compact
 497 .It Dv PT_NULL
 498 The array element is unused and the other members' values are undefined.
 499 This lets the program header have ignored entries.
 500 .It Dv PT_LOAD
 501 The array element specifies a loadable segment, described by
 502 .Fa p_filesz
 503 and
 504 .Fa p_memsz .
 505 The bytes from the file are mapped to the beginning of the memory
 506 segment.
 507 If the segment's memory size
 508 .Pq Fa p_memsz
 509 is larger than the file size
 510 .Pq Fa p_filesz ,
 511 the
 512 .Dq extra
 513 bytes are defined to hold the value 0 and to follow the segment's
 514 initialized area.
 515 The file size may not be larger than the memory size.
 516 Loadable segment entries in the program header table appear in ascending
 517 order, sorted on the
 518 .Fa p_vaddr
 519 member.
 520 .It Dv PT_DYNAMIC
 521 The array element specifies dynamic linking information.
 522 .It Dv PT_INTERP
 523 The array element specifies the location and size of a null-terminated
 524 path name to invoke as an interpreter.
 525 This segment type is meaningful
 526 only for executable files (though it may occur for shared objects).
 527 However, it may not occur more than once in a file.
 528 If it is present it must precede
 529 any loadable segment entry.
 530 .It Dv PT_NOTE
 531 The array element specifies the location and size for auxiliary information.
 532 .It Dv PT_SHLIB
 533 This segment type is reserved but has unspecified semantics.
 534 Programs that
 535 contain an array element of this type do not conform to the ABI.
 536 .It Dv PT_PHDR
 537 The array element, if present, specifies the location and size of the program
 538 header table itself, both in the file and in the memory image of the program.
 539 This segment type may not occur more than once in a file.
 540 Moreover, it may
 541 only occur if the program header table is part of the memory image of the
 542 program.
 543 If it is present it must precede any loadable segment entry.
 544 .It Dv PT_LOPROC
 545 This value up to and including
 546 .Dv PT_HIPROC
 547 are reserved for processor-specific semantics.
 548 .It Dv PT_HIPROC
 549 This value down to and including
 550 .Dv PT_LOPROC
 551 are reserved for processor-specific semantics.
 552 .El
 553 .Pp
 554 .It Fa p_offset
 555 This member holds the offset from the beginning of the file at which
 556 the first byte of the segment resides.
 557 .It Fa p_vaddr
 558 This member holds the virtual address at which the first byte of the
 559 segment resides in memory.
 560 .It Fa p_paddr
 561 On systems for which physical addressing is relevant, this member is
 562 reserved for the segment's physical address.
 563 Under
 564 .Bx
 565 this member is
 566 not used and must be zero.
 567 .It Fa p_filesz
 568 This member holds the number of bytes in the file image of the segment.
 569 It may be zero.
 570 .It Fa p_memsz
 571 This member holds the number of bytes in the memory image of the segment.
 572 It may be zero.
 573 .It Fa p_flags
 574 This member holds flags relevant to the segment:
 575 .Pp
 576 .Bl -tag -width ".Dv PF_X" -compact
 577 .It Dv PF_X
 578 An executable segment.
 579 .It Dv PF_W
 580 A writable segment.
 581 .It Dv PF_R
 582 A readable segment.
 583 .El
 584 .Pp
 585 A text segment commonly has the flags
 586 .Dv PF_X
 587 and
 588 .Dv PF_R .
 589 A data segment commonly has
 590 .Dv PF_X ,
 591 .Dv PF_W
 592 and
 593 .Dv PF_R .
 594 .It Fa p_align
 595 This member holds the value to which the segments are aligned in memory
 596 and in the file.
 597 Loadable process segments must have congruent values for
 598 .Fa p_vaddr
 599 and
 600 .Fa p_offset ,
 601 modulo the page size.
 602 Values of zero and one mean no alignment is required.
 603 Otherwise,
 604 .Fa p_align
 605 should be a positive, integral power of two, and
 606 .Fa p_vaddr
 607 should equal
 608 .Fa p_offset ,
 609 modulo
 610 .Fa p_align .
 611 .El
 612 .Pp
 613 An file's section header table lets one locate all the file's sections.
 614 The
 615 section header table is an array of
 616 .Vt Elf32_Shdr
 617 or
 618 .Vt Elf64_Shdr
 619 structures.
 620 The ELF header's
 621 .Fa e_shoff
 622 member gives the byte offset from the beginning of the file to the section
 623 header table.
 624 .Fa e_shnum
 625 holds the number of entries the section header table contains.
 626 .Fa e_shentsize
 627 holds the size in bytes of each entry.
 628 .Pp
 629 A section header table index is a subscript into this array.
 630 Some section
 631 header table indices are reserved.
 632 An object file does not have sections for
 633 these special indices:
 634 .Pp
 635 .Bl -tag -width ".Dv SHN_LORESERVE" -compact
 636 .It Dv SHN_UNDEF
 637 This value marks an undefined, missing, irrelevant, or otherwise meaningless
 638 section reference.
 639 .It Dv SHN_LORESERVE
 640 This value specifies the lower bound of the range of reserved indices.
 641 .It Dv SHN_LOPROC
 642 This value up to and including
 643 .Dv SHN_HIPROC
 644 are reserved for processor-specific semantics.
 645 .It Dv SHN_HIPROC
 646 This value down to and including
 647 .Dv SHN_LOPROC
 648 are reserved for processor-specific semantics.
 649 .It Dv SHN_ABS
 650 This value specifies absolute values for the corresponding reference.
 651 For
 652 example, symbols defined relative to section number
 653 .Dv SHN_ABS
 654 have absolute values and are not affected by relocation.
 655 .It Dv SHN_COMMON
 656 Symbols defined relative to this section are common symbols, such as FORTRAN
 657 COMMON or unallocated C external variables.
 658 .It Dv SHN_HIRESERVE
 659 This value specifies the upper bound of the range of reserved indices.
 660 The
 661 system reserves indices between
 662 .Dv SHN_LORESERVE
 663 and
 664 .Dv SHN_HIRESERVE ,
 665 inclusive.
 666 The section header table does not contain entries for the
 667 reserved indices.
 668 .El
 669 .Pp
 670 The section header has the following structure:
 671 .Bd -literal -offset indent
 672 typedef struct {
 673         Elf32_Word      sh_name;
 674         Elf32_Word      sh_type;
 675         Elf32_Word      sh_flags;
 676         Elf32_Addr      sh_addr;
 677         Elf32_Off       sh_offset;
 678         Elf32_Size      sh_size;
 679         Elf32_Word      sh_link;
 680         Elf32_Word      sh_info;
 681         Elf32_Size      sh_addralign;
 682         Elf32_Size      sh_entsize;
 683 } Elf32_Shdr;
 684 .Ed
 685 .Bd -literal -offset indent
 686 typedef struct {
 687         Elf64_Half      sh_name;
 688         Elf64_Half      sh_type;
 689         Elf64_Size      sh_flags;
 690         Elf64_Addr      sh_addr;
 691         Elf64_Off       sh_offset;
 692         Elf64_Size      sh_size;
 693         Elf64_Half      sh_link;
 694         Elf64_Half      sh_info;
 695         Elf64_Size      sh_addralign;
 696         Elf64_Size      sh_entsize;
 697 } Elf64_Shdr;
 698 .Ed
 699 .Pp
 700 .Bl -tag -width ".Fa sh_addralign" -compact
 701 .It Fa sh_name
 702 This member specifies the name of the section.
 703 Its value is an index
 704 into the section header string table section, giving the location of
 705 a null-terminated string.
 706 .It Fa sh_type
 707 This member categorizes the section's contents and semantics.
 708 .Pp
 709 .Bl -tag -width ".Dv SHT_PROGBITS" -compact
 710 .It Dv SHT_NULL
 711 This value marks the section header as inactive.
 712 It does not
 713 have an associated section.
 714 Other members of the section header
 715 have undefined values.
 716 .It Dv SHT_PROGBITS
 717 The section holds information defined by the program, whose
 718 format and meaning are determined solely by the program.
 719 .It Dv SHT_SYMTAB
 720 This section holds a symbol table.
 721 Typically,
 722 .Dv SHT_SYMTAB
 723 provides symbols for link editing, though it may also be used
 724 for dynamic linking.
 725 As a complete symbol table, it may contain
 726 many symbols unnecessary for dynamic linking.
 727 An object file can
 728 also contain a
 729 .Dv SHN_DYNSYM
 730 section.
 731 .It Dv SHT_STRTAB
 732 This section holds a string table.
 733 An object file may have multiple
 734 string table sections.
 735 .It Dv SHT_RELA
 736 This section holds relocation entries with explicit addends, such
 737 as type
 738 .Vt Elf32_Rela
 739 for the 32-bit class of object files.
 740 An object may have multiple
 741 relocation sections.
 742 .It Dv SHT_HASH
 743 This section holds a symbol hash table.
 744 All object participating in
 745 dynamic linking must contain a symbol hash table.
 746 An object file may
 747 have only one hash table.
 748 .It Dv SHT_DYNAMIC
 749 This section holds information for dynamic linking.
 750 An object file may
 751 have only one dynamic section.
 752 .It Dv SHT_NOTE
 753 This section holds information that marks the file in some way.
 754 .It Dv SHT_NOBITS
 755 A section of this type occupies no space in the file but otherwise
 756 resembles
 757 .Dv SHN_PROGBITS .
 758 Although this section contains no bytes, the
 759 .Fa sh_offset
 760 member contains the conceptual file offset.
 761 .It Dv SHT_REL
 762 This section holds relocation offsets without explicit addends, such
 763 as type
 764 .Vt Elf32_Rel
 765 for the 32-bit class of object files.
 766 An object file may have multiple
 767 relocation sections.
 768 .It Dv SHT_SHLIB
 769 This section is reserved but has unspecified semantics.
 770 .It Dv SHT_DYNSYM
 771 This section holds a minimal set of dynamic linking symbols.
 772 An
 773 object file can also contain a
 774 .Dv SHN_SYMTAB
 775 section.
 776 .It Dv SHT_LOPROC
 777 This value up to and including
 778 .Dv SHT_HIPROC
 779 are reserved for processor-specific semantics.
 780 .It Dv SHT_HIPROC
 781 This value down to and including
 782 .Dv SHT_LOPROC
 783 are reserved for processor-specific semantics.
 784 .It Dv SHT_LOUSER
 785 This value specifies the lower bound of the range of indices reserved for
 786 application programs.
 787 .It Dv SHT_HIUSER
 788 This value specifies the upper bound of the range of indices reserved for
 789 application programs.
 790 Section types between
 791 .Dv SHT_LOUSER
 792 and
 793 .Dv SHT_HIUSER
 794 may be used by the application, without conflicting with current or future
 795 system-defined section types.
 796 .El
 797 .Pp
 798 .It Fa sh_flags
 799 Sections support one-bit flags that describe miscellaneous attributes.
 800 If a flag bit is set in
 801 .Fa sh_flags ,
 802 the attribute is
 803 .Dq on
 804 for the section.
 805 Otherwise, the attribute is
 806 .Dq off
 807 or does not apply.
 808 Undefined attributes are set to zero.
 809 .Pp
 810 .Bl -tag -width ".Dv SHF_EXECINSTR" -compact
 811 .It Dv SHF_WRITE
 812 This section contains data that should be writable during process
 813 execution.
 814 .It Dv SHF_ALLOC
 815 The section occupies memory during process execution.
 816 Some control
 817 sections do not reside in the memory image of an object file.
 818 This
 819 attribute is off for those sections.
 820 .It Dv SHF_EXECINSTR
 821 The section contains executable machine instructions.
 822 .It Dv SHF_MASKPROC
 823 All bits included in this mask are reserved for processor-specific
 824 semantics.
 825 .El
 826 .Pp
 827 .It Fa sh_addr
 828 If the section will appear in the memory image of a process, this member
 829 holds the address at which the section's first byte should reside.
 830 Otherwise, the member contains zero.
 831 .It Fa sh_offset
 832 This member's value holds the byte offset from the beginning of the file
 833 to the first byte in the section.
 834 One section type,
 835 .Dv SHT_NOBITS ,
 836 occupies no space in the file, and its
 837 .Fa sh_offset
 838 member locates the conceptual placement in the file.
 839 .It Fa sh_size
 840 This member holds the section's size in bytes.
 841 Unless the section type
 842 is
 843 .Dv SHT_NOBITS ,
 844 the section occupies
 845 .Fa sh_size
 846 bytes in the file.
 847 A section of type
 848 .Dv SHT_NOBITS
 849 may have a non-zero size, but it occupies no space in the file.
 850 .It Fa sh_link
 851 This member holds a section header table index link, whose interpretation
 852 depends on the section type.
 853 .It Fa sh_info
 854 This member holds extra information, whose interpretation depends on the
 855 section type.
 856 .It Fa sh_addralign
 857 Some sections have address alignment constraints.
 858 If a section holds a
 859 doubleword, the system must ensure doubleword alignment for the entire
 860 section.
 861 That is, the value of
 862 .Fa sh_addr
 863 must be congruent to zero, modulo the value of
 864 .Fa sh_addralign .
 865 Only zero and positive integral powers of two are allowed.
 866 Values of zero
 867 or one mean the section has no alignment constraints.
 868 .It Fa sh_entsize
 869 Some sections hold a table of fixed-sized entries, such as a symbol table.
 870 For such a section, this member gives the size in bytes for each entry.
 871 This member contains zero if the section does not hold a table of
 872 fixed-size entries.
 873 .El
 874 .Pp
 875 Various sections hold program and control information:
 876 .Bl -tag -width ".Sy .shstrtab" -compact
 877 .It Sy .bss
 878 (Block Started by Symbol)
 879 This section holds uninitialized data that contributes to the program's
 880 memory image.
 881 By definition, the system initializes the data with zeros
 882 when the program begins to run.
 883 This section is of type
 884 .Dv SHT_NOBITS .
 885 The attributes types are
 886 .Dv SHF_ALLOC
 887 and
 888 .Dv SHF_WRITE .
 889 .It Sy .comment
 890 This section holds version control information.
 891 This section is of type
 892 .Dv SHT_PROGBITS .
 893 No attribute types are used.
 894 .It Sy .data
 895 This section holds initialized data that contribute to the program's
 896 memory image.
 897 This section is of type
 898 .Dv SHT_PROGBITS .
 899 The attribute types are
 900 .Dv SHF_ALLOC
 901 and
 902 .Dv SHF_WRITE .
 903 .It Sy .data1
 904 This section holds initialized data that contribute to the program's
 905 memory image.
 906 This section is of type
 907 .Dv SHT_PROGBITS .
 908 The attribute types are
 909 .Dv SHF_ALLOC
 910 and
 911 .Dv SHF_WRITE .
 912 .It Sy .debug
 913 This section holds information for symbolic debugging.
 914 The contents
 915 are unspecified.
 916 This section is of type
 917 .Dv SHT_PROGBITS .
 918 No attribute types are used.
 919 .It Sy .dynamic
 920 This section holds dynamic linking information.
 921 The section's attributes
 922 will include the
 923 .Dv SHF_ALLOC
 924 bit.
 925 Whether the
 926 .Dv SHF_WRITE
 927 bit is set is processor-specific.
 928 This section is of type
 929 .Dv SHT_DYNAMIC .
 930 See the attributes above.
 931 .It Sy .dynstr
 932 This section holds strings needed for dynamic linking, most commonly
 933 the strings that represent the names associated with symbol table entries.
 934 This section is of type
 935 .Dv SHT_STRTAB .
 936 The attribute type used is
 937 .Dv SHF_ALLOC .
 938 .It Sy .dynsym
 939 This section holds the dynamic linking symbol table.
 940 This section is of type
 941 .Dv SHT_DYNSYM .
 942 The attribute used is
 943 .Dv SHF_ALLOC .
 944 .It Sy .fini
 945 This section holds executable instructions that contribute to the process
 946 termination code.
 947 When a program exits normally the system arranges to
 948 execute the code in this section.
 949 This section is of type
 950 .Dv SHT_PROGBITS .
 951 The attributes used are
 952 .Dv SHF_ALLOC
 953 and
 954 .Dv SHF_EXECINSTR .
 955 .It Sy .got
 956 This section holds the global offset table.
 957 This section is of type
 958 .Dv SHT_PROGBITS .
 959 The attributes are processor-specific.
 960 .It Sy .hash
 961 This section holds a symbol hash table.
 962 This section is of type
 963 .Dv SHT_HASH .
 964 The attribute used is
 965 .Dv SHF_ALLOC .
 966 .It Sy .init
 967 This section holds executable instructions that contribute to the process
 968 initialization code.
 969 When a program starts to run the system arranges to
 970 execute the code in this section before calling the main program entry point.
 971 This section is of type
 972 .Dv SHT_PROGBITS .
 973 The attributes used are
 974 .Dv SHF_ALLOC
 975 and
 976 .Dv SHF_EXECINSTR .
 977 .It Sy .interp
 978 This section holds the pathname of a program interpreter.
 979 If the file has
 980 a loadable segment that includes the section, the section's attributes will
 981 include the
 982 .Dv SHF_ALLOC
 983 bit.
 984 Otherwise, that bit will be off.
 985 This section is of type
 986 .Dv SHT_PROGBITS .
 987 .It Sy .line
 988 This section holds line number information for symbolic debugging, which
 989 describes the correspondence between the program source and the machine code.
 990 The contents are unspecified.
 991 This section is of type
 992 .Dv SHT_PROGBITS .
 993 No attribute types are used.
 994 .It Sy .note
 995 This section holds information in the
 996 .Dq Note Section
 997 format described below.
 998 This section is of type
 999 .Dv SHT_NOTE .
1000 No attribute types are used.
1001 .It Sy .plt
1002 This section holds the procedure linkage table.
1003 This section is of type
1004 .Dv SHT_PROGBITS .
1005 The attributes are processor-specific.
1006 .It Sy .relNAME
1007 This section holds relocation information as described below.
1008 If the file
1009 has a loadable segment that includes relocation, the section's attributes
1010 will include the
1011 .Dv SHF_ALLOC
1012 bit.
1013 Otherwise the bit will be off.
1014 By convention,
1015 .Dq NAME
1016 is supplied by the section to which the relocations apply.
1017 Thus a relocation
1018 section for
1019 .Sy .text
1020 normally would have the name
1021 .Sy .rel.text .
1022 This section is of type
1023 .Dv SHT_REL .
1024 .It Sy .relaNAME
1025 This section holds relocation information as described below.
1026 If the file
1027 has a loadable segment that includes relocation, the section's attributes
1028 will include the
1029 .Dv SHF_ALLOC
1030 bit.
1031 Otherwise the bit will be off.
1032 By convention,
1033 .Dq NAME
1034 is supplied by the section to which the relocations apply.
1035 Thus a relocation
1036 section for
1037 .Sy .text
1038 normally would have the name
1039 .Sy .rela.text .
1040 This section is of type
1041 .Dv SHT_RELA .
1042 .It Sy .rodata
1043 This section holds read-only data that typically contributes to a
1044 non-writable segment in the process image.
1045 This section is of type
1046 .Dv SHT_PROGBITS .
1047 The attribute used is
1048 .Dv SHF_ALLOC .
1049 .It Sy .rodata1
1050 This section hold read-only data that typically contributes to a
1051 non-writable segment in the process image.
1052 This section is of type
1053 .Dv SHT_PROGBITS .
1054 The attribute used is
1055 .Dv SHF_ALLOC .
1056 .It Sy .shstrtab
1057 This section holds section names.
1058 This section is of type
1059 .Dv SHT_STRTAB .
1060 No attribute types are used.
1061 .It Sy .strtab
1062 This section holds strings, most commonly the strings that represent the
1063 names associated with symbol table entries.
1064 If the file has a loadable
1065 segment that includes the symbol string table, the section's attributes
1066 will include the
1067 .Dv SHF_ALLOC
1068 bit.
1069 Otherwise the bit will be off.
1070 This section is of type
1071 .Dv SHT_STRTAB .
1072 .It Sy .symtab
1073 This section holds a symbol table.
1074 If the file has a loadable segment
1075 that includes the symbol table, the section's attributes will include
1076 the
1077 .Dv SHF_ALLOC
1078 bit.
1079 Otherwise the bit will be off.
1080 This section is of type
1081 .Dv SHT_SYMTAB .
1082 .It Sy .text
1083 This section holds the
1084 .Dq text ,
1085 or executable instructions, of a program.
1086 This section is of type
1087 .Dv SHT_PROGBITS .
1088 The attributes used are
1089 .Dv SHF_ALLOC
1090 and
1091 .Dv SHF_EXECINSTR .
1092 .El
1093 .Pp
1094 String table sections hold null-terminated character sequences, commonly
1095 called strings.
1096 The object file uses these strings to represent symbol
1097 and section names.
1098 One references a string as an index into the string
1099 table section.
1100 The first byte, which is index zero, is defined to hold
1101 a null character.
1102 Similarly, a string table's last byte is defined to
1103 hold a null character, ensuring null termination for all strings.
1104 .Pp
1105 An object file's symbol table holds information needed to locate and
1106 relocate a program's symbolic definitions and references.
1107 A symbol table
1108 index is a subscript into this array.
1109 .Bd -literal -offset indent
1110 typedef struct {
1111         Elf32_Word      st_name;
1112         Elf32_Addr      st_value;
1113         Elf32_Size      st_size;
1114         unsigned char   st_info;
1115         unsigned char   st_other;
1116         Elf32_Half      st_shndx;
1117 } Elf32_Sym;
1118 .Ed
1119 .Bd -literal -offset indent
1120 typedef struct {
1121         Elf64_Half      st_name;
1122         unsigned char   st_info;
1123         unsigned char   st_other;
1124         Elf64_Quarter   st_shndx;
1125         Elf64_Addr      st_value;
1126         Elf64_Size      st_size;
1127 } Elf64_Sym;
1128 .Ed
1129 .Pp
1130 .Bl -tag -width ".Fa st_value" -compact
1131 .It Fa st_name
1132 This member holds an index into the object file's symbol string table,
1133 which holds character representations of the symbol names.
1134 If the value
1135 is non-zero, it represents a string table index that gives the symbol
1136 name.
1137 Otherwise, the symbol table has no name.
1138 .It Fa st_value
1139 This member gives the value of the associated symbol.
1140 .It Fa st_size
1141 Many symbols have associated sizes.
1142 This member holds zero if the symbol
1143 has no size or an unknown size.
1144 .It Fa st_info
1145 This member specifies the symbol's type and binding attributes:
1146 .Pp
1147 .Bl -tag -width ".Dv STT_SECTION" -compact
1148 .It Dv STT_NOTYPE
1149 The symbol's type is not defined.
1150 .It Dv STT_OBJECT
1151 The symbol is associated with a data object.
1152 .It Dv STT_FUNC
1153 The symbol is associated with a function or other executable code.
1154 .It Dv STT_SECTION
1155 The symbol is associated with a section.
1156 Symbol table entries of
1157 this type exist primarily for relocation and normally have
1158 .Dv STB_LOCAL
1159 bindings.
1160 .It Dv STT_FILE
1161 By convention the symbol's name gives the name of the source file
1162 associated with the object file.
1163 A file symbol has
1164 .Dv STB_LOCAL
1165 bindings, its section index is
1166 .Dv SHN_ABS ,
1167 and it precedes the other
1168 .Dv STB_LOCAL
1169 symbols of the file, if it is present.
1170 .It Dv STT_LOPROC
1171 This value up to and including
1172 .Dv STT_HIPROC
1173 are reserved for processor-specific semantics.
1174 .It Dv STT_HIPROC
1175 This value down to and including
1176 .Dv STT_LOPROC
1177 are reserved for processor-specific semantics.
1178 .El
1179 .Pp
1180 .Bl -tag -width ".Dv STB_GLOBAL" -compact
1181 .It Dv STB_LOCAL
1182 Local symbols are not visible outside the object file containing their
1183 definition.
1184 Local symbols of the same name may exist in multiple file
1185 without interfering with each other.
1186 .It Dv STB_GLOBAL
1187 Global symbols are visible to all object files being combined.
1188 One file's
1189 definition of a global symbol will satisfy another file's undefined
1190 reference to the same symbol.
1191 .It Dv STB_WEAK
1192 Weak symbols resemble global symbols, but their definitions have lower
1193 precedence.
1194 .It Dv STB_LOPROC
1195 This value up to and including
1196 .Dv STB_HIPROC
1197 are reserved for processor-specific semantics.
1198 .It Dv STB_HIPROC
1199 This value down to and including
1200 .Dv STB_LOPROC
1201 are reserved for processor-specific semantics.
1202 .Pp
1203 There are macros for packing and unpacking the binding and type fields:
1204 .Pp
1205 .Bl -tag -width ".Fn ELF32_ST_INFO bind type" -compact
1206 .It Xo
1207 .Fn ELF32_ST_BIND info
1208 .Xc
1209 or
1210 .Fn ELF64_ST_BIND info
1211 extract a binding from an
1212 .Fa st_info
1213 value.
1214 .It Xo
1215 .Fn ELF64_ST_TYPE info
1216 .Xc
1217 or
1218 .Fn ELF32_ST_TYPE info
1219 extract a type from an
1220 .Fa st_info
1221 value.
1222 .It Xo
1223 .Fn ELF32_ST_INFO bind type
1224 .Xc
1225 or
1226 .Fn ELF64_ST_INFO bind type
1227 convert a binding and a type into an
1228 .Fa st_info
1229 value.
1230 .El
1231 .El
1232 .Pp
1233 .It Fa st_other
1234 This member currently holds zero and has no defined meaning.
1235 .It Fa st_shndx
1236 Every symbol table entry is
1237 .Dq defined
1238 in relation to some section.
1239 This member holds the relevant section
1240 header table index.
1241 .El
1242 .Pp
1243 Relocation is the process of connecting symbolic references with
1244 symbolic definitions.
1245 Relocatable files must have information that
1246 describes how to modify their section contents, thus allowing executable
1247 and shared object files to hold the right information for a process'
1248 program image.
1249 Relocation entries are these data.
1250 .Pp
1251 Relocation structures that do not need an addend:
1252 .Bd -literal -offset indent
1253 typedef struct {
1254         Elf32_Addr      r_offset;
1255         Elf32_Word      r_info;
1256 } Elf32_Rel;
1257 .Ed
1258 .Bd -literal -offset indent
1259 typedef struct {
1260         Elf64_Addr      r_offset;
1261         Elf64_Size      r_info;
1262 } Elf64_Rel;
1263 .Ed
1264 .Pp
1265 Relocation structures that need an addend:
1266 .Bd -literal -offset indent
1267 typedef struct {
1268         Elf32_Addr      r_offset;
1269         Elf32_Word      r_info;
1270         Elf32_Sword     r_addend;
1271 } Elf32_Rela;
1272 .Ed
1273 .Bd -literal -offset indent
1274 typedef struct {
1275         Elf64_Addr      r_offset;
1276         Elf64_Size      r_info;
1277         Elf64_Off       r_addend;
1278 } Elf64_Rela;
1279 .Ed
1280 .Pp
1281 .Bl -tag -width ".Fa r_offset" -compact
1282 .It Fa r_offset
1283 This member gives the location at which to apply the relocation action.
1284 For a relocatable file, the value is the byte offset from the beginning
1285 of the section to the storage unit affected by the relocation.
1286 For an
1287 executable file or shared object, the value is the virtual address of
1288 the storage unit affected by the relocation.
1289 .It Fa r_info
1290 This member gives both the symbol table index with respect to which the
1291 relocation must be made and the type of relocation to apply.
1292 Relocation
1293 types are processor-specific.
1294 When the text refers to a relocation
1295 entry's relocation type or symbol table index, it means the result of
1296 applying
1297 .Fn ELF[32|64]_R_TYPE
1298 or
1299 .Fn ELF[32|64]_R_SYM ,
1300 respectively to the entry's
1301 .Fa r_info
1302 member.
1303 .It Fa r_addend
1304 This member specifies a constant addend used to compute the value to be
1305 stored into the relocatable field.
1306 .El
1307 .Sh SEE ALSO
1308 .Xr as 1 ,
1309 .Xr gdb 1 ,
1310 .Xr ld 1 ,
1311 .Xr objdump 1 ,
1312 .Xr readelf 1 ,
1313 .Xr execve 2 ,
1314 .Xr core 5
1315 .Rs
1316 .%A Hewlett Packard
1317 .%B Elf-64 Object File Format
1318 .Re
1319 .Rs
1320 .%A Santa Cruz Operation
1321 .%B System V Application Binary Interface
1322 .Re
1323 .Rs
1324 .%A Unix System Laboratories
1325 .%T Object Files
1326 .%B "Executable and Linking Format (ELF)"
1327 .Re
1328 .Sh HISTORY
1329 The ELF header files made their appearance in
1330 .Fx 2.2.6 .
1331 ELF in itself first appeared in
1332 .At V .
1333 The ELF format is an adopted standard.
1334 .Sh AUTHORS
1335 This manual page was written by
1336 .An Jeroen Ruigrok van der Werven
1337 .Aq asmodai@FreeBSD.org
1338 with inspiration from BSDi's
1339 .Bsx
1340 .Xr elf 5
1341 manpage.