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