pintos-os.org Git - pintos-anon/blob - specs/sysv-abi-update.html/ch4.symtab.html

   1 <html>
   2 <title>Symbol Table</title><p>
   3 <h1>Symbol Table</h1><p>
   4 An object file's symbol table holds information
   5 needed to locate and relocate a program's symbolic
   6 definitions and references.
   7 A symbol table index is a subscript into this array.
   8 Index 0 both designates the first entry in the table
   9 and serves as the undefined symbol index.  The contents of the
  10 initial entry are specified later in this section.
  11 <p>
  12 <table border cellspacing=0>
  13 <th>Name</th>
  14 <th>Value</th>
  15 <tr>
  16 <td><code>STN_UNDEF</code></td>
  17 <td align=center><code>0</code></td>
  18 </tr>
  19 </table>
  20 <p>
  21 A symbol table entry has the following format.
  22 <hr>
  23 <b>Figure 4-16: Symbol Table Entry</b>
  24 <p>
  25 <pre>
  26 <code>
  27 typedef struct {
  28         Elf32_Word      st_name;
  29         Elf32_Addr      st_value;
  30         Elf32_Word      st_size;
  31         unsigned char   st_info;
  32         unsigned char   st_other;
  33         Elf32_Half      st_shndx;
  34 } Elf32_Sym;
  35
  36 typedef struct {
  37         Elf64_Word      st_name;
  38         unsigned char   st_info;
  39         unsigned char   st_other;
  40         Elf64_Half      st_shndx;
  41         Elf64_Addr      st_value;
  42         Elf64_Xword     st_size;
  43 } Elf64_Sym;
  44 </pre>
  45 </code>
  46 <hr>
  47 <p>
  48 <DL COMPACT>
  49 <p><dt><code>st_name</code><dd>
  50 This member holds an index into the object file's
  51 symbol string table, which
  52 holds the character representations of the symbol names.
  53 If the value is non-zero, it represents a string table
  54 index that gives the symbol name.
  55 Otherwise, the symbol table entry has no name.
  56 </dl>
  57 <hr>
  58 <img src=warning.gif alt="NOTE:">
  59 External C symbols have the same names in C
  60 and object files' symbol tables.
  61 <hr><p>
  62 <DL COMPACT>
  63 <p><dt><code>st_value</code><dd>
  64 This member gives the value of the associated symbol.
  65 Depending on the context, this may be an absolute value,
  66 an address, and so on; details appear below.
  67 <p><dt><code>st_size</code><dd>
  68 Many symbols have associated sizes.
  69 For example, a data object's size is the number
  70 of bytes contained in the object.
  71 This member holds 0 if the symbol has no size or an unknown size.
  72 <p><dt><code>st_info</code><dd>
  73 This member specifies the symbol's type and binding attributes.
  74 A list of the values and meanings appears below.
  75 The following code shows how to manipulate the values for
  76 both 32 and 64-bit objects.
  77 <hr>
  78 <PRE>
  79    #define ELF32_ST_BIND(i)   ((i)&gt;&gt;4)
  80    #define ELF32_ST_TYPE(i)   ((i)&amp;0xf)
  81    #define ELF32_ST_INFO(b,t) (((b)&lt;&lt;4)+((t)&amp;0xf))
  82
  83    #define ELF64_ST_BIND(i)   ((i)&gt;&gt;4)
  84    #define ELF64_ST_TYPE(i)   ((i)&amp;0xf)
  85    #define ELF64_ST_INFO(b,t) (((b)&lt;&lt;4)+((t)&amp;0xf))
  86 </PRE>
  87 <hr>
  88 <a name=st_other></a>
  89 <p><dt><code>st_other</code><dd>
  90 This member currently specifies a symbol's visibility.
  91 A list of the values and meanings appears <a href=#visibility>below</a>.
  92 The following code shows how to manipulate the values for
  93 both 32 and 64-bit objects.  Other bits contain 0 and have
  94 no defined meaning.
  95 <hr>
  96 <PRE>
  97    #define ELF32_ST_VISIBILITY(o) ((o)&amp;0x3)
  98    #define ELF64_ST_VISIBILITY(o) ((o)&amp;0x3)
  99 </PRE>
 100 <hr>
 101 <p><dt><code>st_shndx</code><dd>
 102 Every symbol table entry is <i>defined</i> in relation
 103 to some section. This member holds the relevant
 104 section header table index.
 105 As the <code>sh_link</code> and <code>sh_info</code> interpretation
 106 <a href=ch4.sheader.html#sh_link>table</a>
 107 and the related text describe,
 108 some section indexes indicate special meanings.
 109 <p>
 110 If this member contains <code>SHN_XINDEX</code>,
 111 then the actual section header index is too large to fit in this field.
 112 The actual value is contained in the associated
 113 section of type <code>SHT_SYMTAB_SHNDX</code>.
 114 </dl>
 115 <p>
 116 A symbol's binding determines the linkage visibility
 117 and behavior.
 118 <hr>
 119 <b>Figure 4-17: Symbol Binding</b>
 120 <p>
 121 <table border cellspacing=0>
 122 <th>Name</th>
 123 <th>Value</th>
 124 <tr>
 125 <td><code>STB_LOCAL</code></td>
 126 <td align=right><code>0</code></td>
 127 </tr>
 128 <tr>
 129 <td><code>STB_GLOBAL</code></td>
 130 <td align=right><code>1</code></td>
 131 </tr>
 132 <tr>
 133 <td><code>STB_WEAK</code></td>
 134 <td align=right><code>2</code></td>
 135 </tr>
 136 <tr>
 137 <td><code>STB_LOOS</code></td>
 138 <td align=right><code>10</code></td>
 139 </tr>
 140 <tr>
 141 <td><code>STB_HIOS</code></td>
 142 <td align=right><code>12</code></td>
 143 </tr>
 144 <tr>
 145 <td><code>STB_LOPROC</code></td>
 146 <td align=right><code>13</code></td>
 147 </tr>
 148 <tr>
 149 <td><code>STB_HIPROC</code></td>
 150 <td align=right><code>15</code></td>
 151 </tr>
 152 </table>
 153 <hr>
 154 <dl compact>
 155 <p><dt><code>STB_LOCAL</code><dd>
 156 Local symbols are not visible outside the object file
 157 containing their definition.
 158 Local symbols of the same name may exist in
 159 multiple files without interfering with each other.
 160 <p><dt><code>STB_GLOBAL</code><dd>
 161 Global symbols are visible to all object files being combined.
 162 One file's definition of a global symbol will satisfy
 163 another file's undefined reference to the same global symbol.
 164 <p><dt><code>STB_WEAK</code><dd>
 165 Weak symbols resemble global symbols, but their
 166 definitions have lower precedence.
 167 <p><dt><code>STB_LOOS</code>&nbsp;through&nbsp;<code>STB_HIOS</code><dd>
 168 Values in this inclusive range
 169 are reserved for operating system-specific semantics.
 170 <p><dt><code>STB_LOPROC</code>&nbsp;through&nbsp;<code>STB_HIPROC</code><dd>
 171 Values in this inclusive range
 172 are reserved for processor-specific semantics.  If meanings are
 173 specified, the processor supplement explains them.
 174 </dl>
 175 <p>
 176 Global and weak symbols differ in two major ways.
 177 <ul>
 178 <p><li>
 179 When the link editor combines several relocatable object files,
 180 it does not allow multiple definitions of <code>STB_GLOBAL</code>
 181 symbols with the same name.
 182 On the other hand, if a defined global symbol exists,
 183 the appearance of a weak symbol with the same name
 184 will not cause an error.
 185 The link editor honors the global definition and ignores
 186 the weak ones.
 187 Similarly, if a common symbol exists
 188 (that is, a symbol whose <code>st_shndx</code>
 189 field holds <code>SHN_COMMON</code>),
 190 the appearance of a weak symbol with the same name will
 191 not cause an error.
 192 The link editor honors the common definition and
 193 ignores the weak ones.
 194 <p><li>
 195 When the link editor searches archive libraries [see ``Archive File''
 196 in Chapter 7],
 197 it extracts archive members that contain definitions of
 198 undefined global symbols.
 199 The member's definition may be either a global or a weak symbol.
 200 The link editor does not
 201 extract archive members to resolve undefined weak symbols.
 202 Unresolved weak symbols have a zero value.
 203 </ul>
 204 <a name="weak_note"></a>
 205 <hr>
 206 <img src=warning.gif alt="NOTE:">
 207 The behavior of weak symbols in areas not specified by this document is
 208 implementation defined.
 209 Weak symbols are intended primarily for use in system software.
 210 Applications using weak symbols are unreliable
 211 since changes in the runtime environment
 212 might cause the execution to fail.
 213 <hr><p>
 214 In each symbol table, all symbols with <code>STB_LOCAL</code>
 215 binding precede the weak and global symbols.
 216 As
 217 <a href=ch4.sheader.html>``Sections''</a>,
 218 above describes,
 219 a symbol table section's <code>sh_info</code>
 220 section header member holds the symbol table index
 221 for the first non-local symbol.
 222 <p>
 223 A symbol's type provides a general classification for
 224 the associated entity.
 225 <hr>
 226 <b>Figure 4-18: Symbol Types</b>
 227 <p>
 228 <table border cellspacing=0>
 229 <th>Name</th>
 230 <th>Value</th>
 231 <tr>
 232 <td><code>STT_NOTYPE</code></td>
 233 <td align=right><code>0</code></td>
 234 </tr>
 235 <tr>
 236 <td><code>STT_OBJECT</code></td>
 237 <td align=right><code>1</code></td>
 238 </tr>
 239 <tr>
 240 <td><code>STT_FUNC</code></td>
 241 <td align=right><code>2</code></td>
 242 </tr>
 243 <tr>
 244 <td><code>STT_SECTION</code></td>
 245 <td align=right><code>3</code></td>
 246 </tr>
 247 <tr>
 248 <td><code>STT_FILE</code></td>
 249 <td align=right><code>4</code></td>
 250 </tr>
 251 <tr>
 252 <td><code>STT_COMMON</code></td>
 253 <td align=right><code>5</code></td>
 254 </tr>
 255 <tr>
 256 <td><code>STT_TLS</code></td>
 257 <td align=right><code>6</code></td>
 258 </tr>
 259 <tr>
 260 <td><code>STT_LOOS</code></td>
 261 <td align=right><code>10</code></td>
 262 </tr>
 263 <tr>
 264 <td><code>STT_HIOS</code></td>
 265 <td align=right><code>12</code></td>
 266 </tr>
 267 <tr>
 268 <td><code>STT_LOPROC</code></td>
 269 <td align=right><code>13</code></td>
 270 </tr>
 271 <tr>
 272 <td><code>STT_HIPROC</code></td>
 273 <td align=right><code>15</code></td>
 274 </tr>
 275 </table>
 276 <hr>
 277 <p>
 278 <DL COMPACT>
 279 <p><dt><code>STT_NOTYPE</code><dd>
 280 The symbol's type is not specified.
 281 <p><dt><code>STT_OBJECT</code><dd>
 282 The symbol is associated with a data object,
 283 such as a variable, an array, and so on.
 284 <p><dt><code>STT_FUNC</code><dd>
 285 The symbol is associated with a function or other executable code.
 286 <p><dt><code>STT_SECTION</code><dd>
 287 The symbol is associated with a section.
 288 Symbol table entries of this type exist primarily for relocation
 289 and normally have <code>STB_LOCAL</code> binding.
 290 <p><dt><code>STT_FILE</code><dd>
 291 Conventionally, the symbol's name gives the name of
 292 the source file associated with the object file.
 293 A file symbol has <code>STB_LOCAL</code>
 294 binding, its section index is <code>SHN_ABS</code>,
 295 and it precedes the other <code>STB_LOCAL</code>
 296 symbols for the file, if it is present.
 297 <p><dt><code>STT_COMMON</code><dd>
 298 The symbol labels an uninitialized common block.
 299 See <a href=#stt_common>below</a> for details.
 300 <a name=stt_tls></a>
 301 <p><dt><code>STT_TLS</code><dd>
 302 The symbol specifies a <i>Thread-Local Storage</i> entity.
 303 When defined, it gives the assigned offset for the symbol,
 304 not the actual address.
 305 Symbols of type <code>STT_TLS</code> can be referenced
 306 by only special thread-local storage relocations
 307 and thread-local storage relocations can only reference
 308 symbols with type <code>STT_TLS</code>.
 309 Implementation need not support thread-local storage.
 310 <p><dt><code>STT_LOOS</code>&nbsp;through&nbsp;<code>STT_HIOS</code><dd>
 311 Values in this inclusive range
 312 are reserved for operating system-specific semantics.
 313 <p><dt><code>STT_LOPROC</code>&nbsp;through&nbsp;<code>STT_HIPROC</code><dd>
 314 Values in this inclusive range
 315 are reserved for processor-specific semantics.
 316 If meanings are specified, the processor supplement explains
 317 them.
 318 </dl>
 319 <p>
 320 Function symbols (those with type
 321 <code>STT_FUNC</code>) in shared object files have special significance.
 322 When another object file references a function from
 323 a shared object, the link editor automatically creates a procedure
 324 linkage table entry for the referenced symbol.
 325 Shared object symbols with types other than
 326 <code>STT_FUNC</code> will not
 327 be referenced automatically through the procedure linkage table.
 328 <a name=stt_common></a>
 329 <p>
 330 Symbols with type <code>STT_COMMON</code> label uninitialized
 331 common blocks.  In relocatable objects, these symbols are
 332 not allocated and must have the special section index
 333 <code>SHN_COMMON</code> (see <a href=#shn_common>below</a>).
 334 In shared objects and executables these symbols must be
 335 allocated to some section in the defining object.
 336 <p>
 337 In relocatable objects, symbols with type <code>STT_COMMON</code>
 338 are treated just as other symbols with index <code>SHN_COMMON</code>.
 339 If the link-editor allocates space for the <code>SHN_COMMON</code>
 340 symbol in an output section of the object it is producing, it
 341 must preserve the type of the output symbol as <code>STT_COMMON</code>.
 342 <p>
 343 When the dynamic linker encounters a reference to a symbol
 344 that resolves to a definition of type <code>STT_COMMON</code>,
 345 it may (but is not required to) change its symbol resolution
 346 rules as follows: instead of binding the reference to
 347 the first symbol found with the given name, the dynamic linker searches
 348 for the first symbol with that name with type other
 349 than <code>STT_COMMON</code>.  If no such symbol is found,
 350 it looks for the <code>STT_COMMON</code> definition of that
 351 name that has the largest size.
 352 <a name=visibility></a>
 353 <p>
 354 A symbol's visibility, although it may be specified in a relocatable
 355 object, defines how that symbol may be accessed once it has
 356 become part of an executable or shared object.
 357 <hr>
 358 <b>Figure 4-19: Symbol Visibility</b>
 359 <p>
 360 <table border cellspacing=0>
 361 <th>Name</th>
 362 <th>Value</th>
 363 <tr>
 364 <td><code>STV_DEFAULT</code></td>
 365 <td align=right><code>0</code></td>
 366 </tr>
 367 <tr>
 368 <td><code>STV_INTERNAL</code></td>
 369 <td align=right><code>1</code></td>
 370 </tr>
 371 <tr>
 372 <td><code>STV_HIDDEN</code></td>
 373 <td align=right><code>2</code></td>
 374 </tr>
 375 <tr>
 376 <td><code>STV_PROTECTED</code></td>
 377 <td align=right><code>3</code></td>
 378 </tr>
 379 </table>
 380 <hr>
 381 <p>
 382 <DL COMPACT>
 383 <p><dt><code>STV_DEFAULT</code><dd>
 384 The visibility of symbols with the <code>STV_DEFAULT</code>
 385 attribute is as specified by the symbol's binding type.
 386 That is, global and weak symbols are visible
 387 outside of their defining <i>component</i>
 388 (executable file or shared object).
 389 Local symbols are <i>hidden</i>, as described below.
 390 Global and weak symbols are also <i>preemptable</i>,
 391 that is, they may by preempted by definitions of the same
 392 name in another component.
 393 <hr>
 394 <img src=warning.gif alt="NOTE:">
 395 An implementation may restrict the set of global and weak
 396 symbols that are externally visible.
 397 <hr><p>
 398 <p><dt><code>STV_PROTECTED</code><dd>
 399 A symbol defined in the current component is <i>protected</i>
 400 if it is visible in other components but not preemptable,
 401 meaning that any reference to such a symbol from within the
 402 defining component must be resolved to the definition in
 403 that component, even if there is a definition in another
 404 component that would preempt by the default rules.
 405 A symbol with <code>STB_LOCAL</code> binding may not have
 406 <code>STV_PROTECTED</code> visibility.
 407 <a name=protected_resolution></a>
 408 If a symbol definition with <code>STV_PROTECTED</code> visibility
 409 from a shared object is taken as resolving a reference
 410 from an executable or another shared object,
 411 the <code>SHN_UNDEF</code> symbol table entry created
 412 has <code>STV_DEFAULT</code> visibility.
 413 <hr>
 414 <img src=warning.gif alt="NOTE:">
 415 <a name=protected_note></a>
 416 The presence of the <code>STV_PROTECTED</code> flag on a symbol
 417 in a given load module does not affect the symbol resolution
 418 rules for references to that symbol from outside the containing
 419 load module.
 420 <hr><p>
 421 <p><dt><code>STV_HIDDEN</code><dd>
 422 A symbol defined in the current component is <i>hidden</i>
 423 if its name is not visible to other components.  Such a symbol
 424 is necessarily protected.  This attribute may be used to
 425 control the external interface of a component.  Note that
 426 an object named by such a symbol may still be referenced
 427 from another component if its address is passed outside.
 428 <p>
 429 A hidden symbol contained in a relocatable object must be
 430 either removed or converted to <code>STB_LOCAL</code> binding
 431 by the link-editor when the relocatable object is included in an
 432 executable file or shared object.
 433 <p><dt><code>STV_INTERNAL</code><dd>
 434 The meaning of this visibility attribute may be defined by processor
 435 supplements to further constrain hidden symbols.  A processor
 436 supplement's definition should be such that generic tools
 437 can safely treat internal symbols as hidden.
 438 <p>
 439 An internal symbol contained in a relocatable object must be
 440 either removed or converted to <code>STB_LOCAL</code> binding
 441 by the link-editor when the relocatable object is included in an
 442 executable file or shared object.
 443 </dl>
 444 <p>
 445 None of the visibility attributes affects resolution of symbols
 446 within an executable or shared object during link-editing -- such
 447 resolution is controlled by the binding type.  Once the link-editor
 448 has chosen its resolution, these attributes impose two requirements,
 449 both based on the fact that references in the code being linked may
 450 have been optimized to take advantage of the attributes.
 451 <ul>
 452 <li>
 453 First, all of the non-default visibility attributes, when applied
 454 to a symbol reference, imply that a definition to satisfy that
 455 reference must be provided within the current executable or
 456 shared object.  If such a symbol reference has no definition within the
 457 component being linked, then the reference must have
 458 <code>STB_WEAK</code> binding and is resolved to zero.
 459 <li>
 460 Second, if any reference to or definition of a name is a symbol with
 461 a non-default visibility attribute, the visibility attribute
 462 must be propagated to the resolving symbol in the linked object.
 463 If different visibility attributes are specified for distinct
 464 references to or definitions of a symbol, the most constraining
 465 visibility attribute must be propagated to the resolving symbol
 466 in the linked object.  The attributes, ordered from least
 467 to most constraining, are: <code>STV_PROTECTED</code>,
 468 <code>STV_HIDDEN</code> and <code>STV_INTERNAL</code>.
 469 </ul>
 470 <p>
 471 If a symbol's value refers to a
 472 specific location within a section,
 473 its section index member, <code>st_shndx</code>,
 474 holds an index into the section header table.
 475 As the section moves during relocation, the symbol's value
 476 changes as well, and references to the symbol
 477 continue to ``point'' to the same location in the program.
 478 Some special section index values give other semantics.
 479 <DL COMPACT>
 480 <p><dt><code>SHN_ABS</code><dd>
 481 The symbol has an absolute value that will not change
 482 because of relocation.
 483 <a name=shn_common></a>
 484 <p><dt><code>SHN_COMMON</code><dd>
 485 The symbol labels a common block that has not yet been allocated.
 486 The symbol's value gives alignment constraints,
 487 similar to a section's
 488 <code>sh_addralign</code> member.
 489 The link editor will allocate the storage for the symbol
 490 at an address that is a multiple of
 491 <code>st_value</code>.
 492 The symbol's size tells how many bytes are required.
 493 Symbols with section index <code>SHN_COMMON</code> may
 494 appear only in relocatable objects.
 495 <p><dt><code>SHN_UNDEF</code><dd>
 496 This section table index means the symbol is undefined.
 497 When the link editor combines this object file with
 498 another that defines the indicated symbol,
 499 this file's references to the symbol will be linked
 500 to the actual definition.
 501 <p><dt><code>SHN_XINDEX</code><dd>
 502 <a name=many_sections></a>
 503 This value is an escape value.
 504 It indicates that the symbol refers to a specific location within a section,
 505 but that the section header index for that section is too large to be
 506 represented directly in the symbol table entry.
 507 The actual section header index is found in the associated
 508 <code>SHT_SYMTAB_SHNDX</code> section.
 509 The entries in that section correspond one to one
 510 with the entries in the symbol table.
 511 Only those entries in <code>SHT_SYMTAB_SHNDX</code>
 512 that correspond to symbol table entries with <code>SHN_XINDEX</code>
 513 will hold valid section header indexes;
 514 all other entries will have value <code>0</code>.
 515 </dl>
 516 <p>
 517 The symbol table entry for index 0 (<code>STN_UNDEF</code>)
 518 is reserved; it holds the following.
 519 <hr>
 520 <b>Figure 4-20: Symbol Table Entry:Index 0</b>
 521 <p>
 522 <table border cellspacing=0>
 523 <th><b>Name</b></th>
 524 <th><b>Value</b></th>
 525 <th><b>Note</b></th>
 526 <tr>
 527 <td><code>st_name</code></td>
 528 <td align=center><code>0</code></td>
 529 <td>No name</td>
 530 </tr>
 531 <tr>
 532 <td><code>st_value</code></td>
 533 <td align=center><code>0</code></td>
 534 <td>Zero value</td>
 535 </tr>
 536 <tr>
 537 <td><code>st_size</code></td>
 538 <td align=center><code>0</code></td>
 539 <td>No size</td>
 540 </tr>
 541 <tr>
 542 <td><code>st_info</code></td>
 543 <td align=center><code>0</code></td>
 544 <td>No type, local binding</td>
 545 </tr>
 546 <tr>
 547 <td><code>st_other</code></td>
 548 <td align=center><code>0</code></td>
 549 <td>Default visibility</td>
 550 </tr>
 551 <tr>
 552 <td><code>st_shndx</code></td>
 553 <td align=center><code>SHN_UNDEF</code></td>
 554 <td>No section</td>
 555 </tr>
 556 </table>
 557 <hr>
 558 <a name=symbol_values></a>
 559 <h2>Symbol Values</h2>
 560 Symbol table entries for different object file types have
 561 slightly different interpretations for the <code>st_value</code> member.
 562 <ul>
 563 <p><li>
 564 In relocatable files, <code>st_value</code> holds alignment constraints for a symbol
 565 whose section index is <code>SHN_COMMON</code>.
 566 <p><li>
 567 In relocatable files, <code>st_value</code> holds
 568 a section offset for a defined symbol.
 569 <code>st_value</code> is an offset from the beginning of the section that
 570 <code>st_shndx</code> identifies.
 571 <p><li>
 572 In executable and shared object files,
 573 <code>st_value</code> holds a virtual address.
 574 To make these files' symbols more useful
 575 for the dynamic linker, the section offset (file interpretation)
 576 gives way to a virtual address (memory interpretation)
 577 for which the section number is irrelevant.
 578 </ul>
 579 Although the symbol table values have similar meanings
 580 for different object files, the data allows
 581 efficient access by the appropriate programs.
 582 <hr>
 583 <a href=ch4.strtab.html><img src=previous.gif alt="Previous"></a>
 584 <a href=contents.html><img src=contents.gif alt="Contents"></a>
 585 <a href=ch4.reloc.html><img src=next.gif alt="Next"></a>
 586 <hr>
 587 <i>
 588 <small>
 589 &#169; 1997, 1998, 1999, 2000, 2001 The Santa Cruz Operation, Inc.  All rights reserved.
 590 </small>
 591 </i>
 592 </html>