share/man/man5/elf.5

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