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