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