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