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