1\input texinfo 2@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 3@c 2000, 2001, 2002, 2003, 2004, 2006, 2007 4@c Free Software Foundation, Inc. 5@setfilename bfdint.info 6 7@settitle BFD Internals 8@iftex 9@titlepage 10@title{BFD Internals} 11@author{Ian Lance Taylor} 12@author{Cygnus Solutions} 13@page 14@end iftex 15 16@copying 17This file documents the internals of the BFD library. 18 19Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 201996, 1998, 2000, 2001, 2002, 2003, 2004, 2006, 2007 21Free Software Foundation, Inc. 22Contributed by Cygnus Support. 23 24Permission is granted to copy, distribute and/or modify this document 25under the terms of the GNU Free Documentation License, Version 1.1 or 26any later version published by the Free Software Foundation; with the 27Invariant Sections being ``GNU General Public License'' and ``Funding 28Free Software'', the Front-Cover texts being (a) (see below), and with 29the Back-Cover Texts being (b) (see below). A copy of the license is 30included in the section entitled ``GNU Free Documentation License''. 31 32(a) The FSF's Front-Cover Text is: 33 34 A GNU Manual 35 36(b) The FSF's Back-Cover Text is: 37 38 You have freedom to copy and modify this GNU Manual, like GNU 39 software. Copies published by the Free Software Foundation raise 40 funds for GNU development. 41@end copying 42 43@node Top 44@top BFD Internals 45@raisesections 46@cindex bfd internals 47 48This document describes some BFD internal information which may be 49helpful when working on BFD. It is very incomplete. 50 51This document is not updated regularly, and may be out of date. 52 53The initial version of this document was written by Ian Lance Taylor 54@email{ian@@cygnus.com}. 55 56@menu 57* BFD overview:: BFD overview 58* BFD guidelines:: BFD programming guidelines 59* BFD target vector:: BFD target vector 60* BFD generated files:: BFD generated files 61* BFD multiple compilations:: Files compiled multiple times in BFD 62* BFD relocation handling:: BFD relocation handling 63* BFD ELF support:: BFD ELF support 64* BFD glossary:: Glossary 65* Index:: Index 66@end menu 67 68@node BFD overview 69@section BFD overview 70 71BFD is a library which provides a single interface to read and write 72object files, executables, archive files, and core files in any format. 73 74@menu 75* BFD library interfaces:: BFD library interfaces 76* BFD library users:: BFD library users 77* BFD view:: The BFD view of a file 78* BFD blindness:: BFD loses information 79@end menu 80 81@node BFD library interfaces 82@subsection BFD library interfaces 83 84One way to look at the BFD library is to divide it into four parts by 85type of interface. 86 87The first interface is the set of generic functions which programs using 88the BFD library will call. These generic function normally translate 89directly or indirectly into calls to routines which are specific to a 90particular object file format. Many of these generic functions are 91actually defined as macros in @file{bfd.h}. These functions comprise 92the official BFD interface. 93 94The second interface is the set of functions which appear in the target 95vectors. This is the bulk of the code in BFD. A target vector is a set 96of function pointers specific to a particular object file format. The 97target vector is used to implement the generic BFD functions. These 98functions are always called through the target vector, and are never 99called directly. The target vector is described in detail in @ref{BFD 100target vector}. The set of functions which appear in a particular 101target vector is often referred to as a BFD backend. 102 103The third interface is a set of oddball functions which are typically 104specific to a particular object file format, are not generic functions, 105and are called from outside of the BFD library. These are used as hooks 106by the linker and the assembler when a particular object file format 107requires some action which the BFD generic interface does not provide. 108These functions are typically declared in @file{bfd.h}, but in many 109cases they are only provided when BFD is configured with support for a 110particular object file format. These functions live in a grey area, and 111are not really part of the official BFD interface. 112 113The fourth interface is the set of BFD support functions which are 114called by the other BFD functions. These manage issues like memory 115allocation, error handling, file access, hash tables, swapping, and the 116like. These functions are never called from outside of the BFD library. 117 118@node BFD library users 119@subsection BFD library users 120 121Another way to look at the BFD library is to divide it into three parts 122by the manner in which it is used. 123 124The first use is to read an object file. The object file readers are 125programs like @samp{gdb}, @samp{nm}, @samp{objdump}, and @samp{objcopy}. 126These programs use BFD to view an object file in a generic form. The 127official BFD interface is normally fully adequate for these programs. 128 129The second use is to write an object file. The object file writers are 130programs like @samp{gas} and @samp{objcopy}. These programs use BFD to 131create an object file. The official BFD interface is normally adequate 132for these programs, but for some object file formats the assembler needs 133some additional hooks in order to set particular flags or other 134information. The official BFD interface includes functions to copy 135private information from one object file to another, and these functions 136are used by @samp{objcopy} to avoid information loss. 137 138The third use is to link object files. There is only one object file 139linker, @samp{ld}. Originally, @samp{ld} was an object file reader and 140an object file writer, and it did the link operation using the generic 141BFD structures. However, this turned out to be too slow and too memory 142intensive. 143 144The official BFD linker functions were written to permit specific BFD 145backends to perform the link without translating through the generic 146structures, in the normal case where all the input files and output file 147have the same object file format. Not all of the backends currently 148implement the new interface, and there are default linking functions 149within BFD which use the generic structures and which work with all 150backends. 151 152For several object file formats the linker needs additional hooks which 153are not provided by the official BFD interface, particularly for dynamic 154linking support. These functions are typically called from the linker 155emulation template. 156 157@node BFD view 158@subsection The BFD view of a file 159 160BFD uses generic structures to manage information. It translates data 161into the generic form when reading files, and out of the generic form 162when writing files. 163 164BFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd} 165is composed of the following elements. The BFD information can be 166displayed using the @samp{objdump} program with various options. 167 168@table @asis 169@item general information 170The object file format, a few general flags, the start address. 171@item architecture 172The architecture, including both a general processor type (m68k, MIPS 173etc.) and a specific machine number (m68000, R4000, etc.). 174@item sections 175A list of sections. 176@item symbols 177A symbol table. 178@end table 179 180BFD represents a section as a pointer to the @samp{asection} type. Each 181section has a name and a size. Most sections also have an associated 182block of data, known as the section contents. Sections also have 183associated flags, a virtual memory address, a load memory address, a 184required alignment, a list of relocations, and other miscellaneous 185information. 186 187BFD represents a relocation as a pointer to the @samp{arelent} type. A 188relocation describes an action which the linker must take to modify the 189section contents. Relocations have a symbol, an address, an addend, and 190a pointer to a howto structure which describes how to perform the 191relocation. For more information, see @ref{BFD relocation handling}. 192 193BFD represents a symbol as a pointer to the @samp{asymbol} type. A 194symbol has a name, a pointer to a section, an offset within that 195section, and some flags. 196 197Archive files do not have any sections or symbols. Instead, BFD 198represents an archive file as a file which contains a list of 199@samp{bfd}s. BFD also provides access to the archive symbol map, as a 200list of symbol names. BFD provides a function to return the @samp{bfd} 201within the archive which corresponds to a particular entry in the 202archive symbol map. 203 204@node BFD blindness 205@subsection BFD loses information 206 207Most object file formats have information which BFD can not represent in 208its generic form, at least as currently defined. 209 210There is often explicit information which BFD can not represent. For 211example, the COFF version stamp, or the ELF program segments. BFD 212provides special hooks to handle this information when copying, 213printing, or linking an object file. The BFD support for a particular 214object file format will normally store this information in private data 215and handle it using the special hooks. 216 217In some cases there is also implicit information which BFD can not 218represent. For example, the MIPS processor distinguishes small and 219large symbols, and requires that all small symbols be within 32K of the 220GP register. This means that the MIPS assembler must be able to mark 221variables as either small or large, and the MIPS linker must know to put 222small symbols within range of the GP register. Since BFD can not 223represent this information, this means that the assembler and linker 224must have information that is specific to a particular object file 225format which is outside of the BFD library. 226 227This loss of information indicates areas where the BFD paradigm breaks 228down. It is not actually possible to represent the myriad differences 229among object file formats using a single generic interface, at least not 230in the manner which BFD does it today. 231 232Nevertheless, the BFD library does greatly simplify the task of dealing 233with object files, and particular problems caused by information loss 234can normally be solved using some sort of relatively constrained hook 235into the library. 236 237 238 239@node BFD guidelines 240@section BFD programming guidelines 241@cindex bfd programming guidelines 242@cindex programming guidelines for bfd 243@cindex guidelines, bfd programming 244 245There is a lot of poorly written and confusing code in BFD. New BFD 246code should be written to a higher standard. Merely because some BFD 247code is written in a particular manner does not mean that you should 248emulate it. 249 250Here are some general BFD programming guidelines: 251 252@itemize @bullet 253@item 254Follow the GNU coding standards. 255 256@item 257Avoid global variables. We ideally want BFD to be fully reentrant, so 258that it can be used in multiple threads. All uses of global or static 259variables interfere with that. Initialized constant variables are OK, 260and they should be explicitly marked with @samp{const}. Instead of global 261variables, use data attached to a BFD or to a linker hash table. 262 263@item 264All externally visible functions should have names which start with 265@samp{bfd_}. All such functions should be declared in some header file, 266typically @file{bfd.h}. See, for example, the various declarations near 267the end of @file{bfd-in.h}, which mostly declare functions required by 268specific linker emulations. 269 270@item 271All functions which need to be visible from one file to another within 272BFD, but should not be visible outside of BFD, should start with 273@samp{_bfd_}. Although external names beginning with @samp{_} are 274prohibited by the ANSI standard, in practice this usage will always 275work, and it is required by the GNU coding standards. 276 277@item 278Always remember that people can compile using @samp{--enable-targets} to 279build several, or all, targets at once. It must be possible to link 280together the files for all targets. 281 282@item 283BFD code should compile with few or no warnings using @samp{gcc -Wall}. 284Some warnings are OK, like the absence of certain function declarations 285which may or may not be declared in system header files. Warnings about 286ambiguous expressions and the like should always be fixed. 287@end itemize 288 289@node BFD target vector 290@section BFD target vector 291@cindex bfd target vector 292@cindex target vector in bfd 293 294BFD supports multiple object file formats by using the @dfn{target 295vector}. This is simply a set of function pointers which implement 296behaviour that is specific to a particular object file format. 297 298In this section I list all of the entries in the target vector and 299describe what they do. 300 301@menu 302* BFD target vector miscellaneous:: Miscellaneous constants 303* BFD target vector swap:: Swapping functions 304* BFD target vector format:: Format type dependent functions 305* BFD_JUMP_TABLE macros:: BFD_JUMP_TABLE macros 306* BFD target vector generic:: Generic functions 307* BFD target vector copy:: Copy functions 308* BFD target vector core:: Core file support functions 309* BFD target vector archive:: Archive functions 310* BFD target vector symbols:: Symbol table functions 311* BFD target vector relocs:: Relocation support 312* BFD target vector write:: Output functions 313* BFD target vector link:: Linker functions 314* BFD target vector dynamic:: Dynamic linking information functions 315@end menu 316 317@node BFD target vector miscellaneous 318@subsection Miscellaneous constants 319 320The target vector starts with a set of constants. 321 322@table @samp 323@item name 324The name of the target vector. This is an arbitrary string. This is 325how the target vector is named in command line options for tools which 326use BFD, such as the @samp{--oformat} linker option. 327 328@item flavour 329A general description of the type of target. The following flavours are 330currently defined: 331 332@table @samp 333@item bfd_target_unknown_flavour 334Undefined or unknown. 335@item bfd_target_aout_flavour 336a.out. 337@item bfd_target_coff_flavour 338COFF. 339@item bfd_target_ecoff_flavour 340ECOFF. 341@item bfd_target_elf_flavour 342ELF. 343@item bfd_target_ieee_flavour 344IEEE-695. 345@item bfd_target_nlm_flavour 346NLM. 347@item bfd_target_oasys_flavour 348OASYS. 349@item bfd_target_tekhex_flavour 350Tektronix hex format. 351@item bfd_target_srec_flavour 352Motorola S-record format. 353@item bfd_target_ihex_flavour 354Intel hex format. 355@item bfd_target_som_flavour 356SOM (used on HP/UX). 357@item bfd_target_os9k_flavour 358os9000. 359@item bfd_target_versados_flavour 360VERSAdos. 361@item bfd_target_msdos_flavour 362MS-DOS. 363@item bfd_target_evax_flavour 364openVMS. 365@item bfd_target_mmo_flavour 366Donald Knuth's MMIXware object format. 367@end table 368 369@item byteorder 370The byte order of data in the object file. One of 371@samp{BFD_ENDIAN_BIG}, @samp{BFD_ENDIAN_LITTLE}, or 372@samp{BFD_ENDIAN_UNKNOWN}. The latter would be used for a format such 373as S-records which do not record the architecture of the data. 374 375@item header_byteorder 376The byte order of header information in the object file. Normally the 377same as the @samp{byteorder} field, but there are certain cases where it 378may be different. 379 380@item object_flags 381Flags which may appear in the @samp{flags} field of a BFD with this 382format. 383 384@item section_flags 385Flags which may appear in the @samp{flags} field of a section within a 386BFD with this format. 387 388@item symbol_leading_char 389A character which the C compiler normally puts before a symbol. For 390example, an a.out compiler will typically generate the symbol 391@samp{_foo} for a function named @samp{foo} in the C source, in which 392case this field would be @samp{_}. If there is no such character, this 393field will be @samp{0}. 394 395@item ar_pad_char 396The padding character to use at the end of an archive name. Normally 397@samp{/}. 398 399@item ar_max_namelen 400The maximum length of a short name in an archive. Normally @samp{14}. 401 402@item backend_data 403A pointer to constant backend data. This is used by backends to store 404whatever additional information they need to distinguish similar target 405vectors which use the same sets of functions. 406@end table 407 408@node BFD target vector swap 409@subsection Swapping functions 410 411Every target vector has function pointers used for swapping information 412in and out of the target representation. There are two sets of 413functions: one for data information, and one for header information. 414Each set has three sizes: 64-bit, 32-bit, and 16-bit. Each size has 415three actual functions: put, get unsigned, and get signed. 416 417These 18 functions are used to convert data between the host and target 418representations. 419 420@node BFD target vector format 421@subsection Format type dependent functions 422 423Every target vector has three arrays of function pointers which are 424indexed by the BFD format type. The BFD format types are as follows: 425 426@table @samp 427@item bfd_unknown 428Unknown format. Not used for anything useful. 429@item bfd_object 430Object file. 431@item bfd_archive 432Archive file. 433@item bfd_core 434Core file. 435@end table 436 437The three arrays of function pointers are as follows: 438 439@table @samp 440@item bfd_check_format 441Check whether the BFD is of a particular format (object file, archive 442file, or core file) corresponding to this target vector. This is called 443by the @samp{bfd_check_format} function when examining an existing BFD. 444If the BFD matches the desired format, this function will initialize any 445format specific information such as the @samp{tdata} field of the BFD. 446This function must be called before any other BFD target vector function 447on a file opened for reading. 448 449@item bfd_set_format 450Set the format of a BFD which was created for output. This is called by 451the @samp{bfd_set_format} function after creating the BFD with a 452function such as @samp{bfd_openw}. This function will initialize format 453specific information required to write out an object file or whatever of 454the given format. This function must be called before any other BFD 455target vector function on a file opened for writing. 456 457@item bfd_write_contents 458Write out the contents of the BFD in the given format. This is called 459by @samp{bfd_close} function for a BFD opened for writing. This really 460should not be an array selected by format type, as the 461@samp{bfd_set_format} function provides all the required information. 462In fact, BFD will fail if a different format is used when calling 463through the @samp{bfd_set_format} and the @samp{bfd_write_contents} 464arrays; fortunately, since @samp{bfd_close} gets it right, this is a 465difficult error to make. 466@end table 467 468@node BFD_JUMP_TABLE macros 469@subsection @samp{BFD_JUMP_TABLE} macros 470@cindex @samp{BFD_JUMP_TABLE} 471 472Most target vectors are defined using @samp{BFD_JUMP_TABLE} macros. 473These macros take a single argument, which is a prefix applied to a set 474of functions. The macros are then used to initialize the fields in the 475target vector. 476 477For example, the @samp{BFD_JUMP_TABLE_RELOCS} macro defines three 478functions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc}, 479and @samp{_bfd_reloc_type_lookup}. A reference like 480@samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions 481prefixed with @samp{foo}: @samp{foo_get_reloc_upper_bound}, etc. The 482@samp{BFD_JUMP_TABLE_RELOCS} macro will be placed such that those three 483functions initialize the appropriate fields in the BFD target vector. 484 485This is done because it turns out that many different target vectors can 486share certain classes of functions. For example, archives are similar 487on most platforms, so most target vectors can use the same archive 488functions. Those target vectors all use @samp{BFD_JUMP_TABLE_ARCHIVE} 489with the same argument, calling a set of functions which is defined in 490@file{archive.c}. 491 492Each of the @samp{BFD_JUMP_TABLE} macros is mentioned below along with 493the description of the function pointers which it defines. The function 494pointers will be described using the name without the prefix which the 495@samp{BFD_JUMP_TABLE} macro defines. This name is normally the same as 496the name of the field in the target vector structure. Any differences 497will be noted. 498 499@node BFD target vector generic 500@subsection Generic functions 501@cindex @samp{BFD_JUMP_TABLE_GENERIC} 502 503The @samp{BFD_JUMP_TABLE_GENERIC} macro is used for some catch all 504functions which don't easily fit into other categories. 505 506@table @samp 507@item _close_and_cleanup 508Free any target specific information associated with the BFD. This is 509called when any BFD is closed (the @samp{bfd_write_contents} function 510mentioned earlier is only called for a BFD opened for writing). Most 511targets use @samp{bfd_alloc} to allocate all target specific 512information, and therefore don't have to do anything in this function. 513This function pointer is typically set to 514@samp{_bfd_generic_close_and_cleanup}, which simply returns true. 515 516@item _bfd_free_cached_info 517Free any cached information associated with the BFD which can be 518recreated later if necessary. This is used to reduce the memory 519consumption required by programs using BFD. This is normally called via 520the @samp{bfd_free_cached_info} macro. It is used by the default 521archive routines when computing the archive map. Most targets do not 522do anything special for this entry point, and just set it to 523@samp{_bfd_generic_free_cached_info}, which simply returns true. 524 525@item _new_section_hook 526This is called from @samp{bfd_make_section_anyway} whenever a new 527section is created. Most targets use it to initialize section specific 528information. This function is called whether or not the section 529corresponds to an actual section in an actual BFD. 530 531@item _get_section_contents 532Get the contents of a section. This is called from 533@samp{bfd_get_section_contents}. Most targets set this to 534@samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek} 535based on the section's @samp{filepos} field and a @samp{bfd_bread}. The 536corresponding field in the target vector is named 537@samp{_bfd_get_section_contents}. 538 539@item _get_section_contents_in_window 540Set a @samp{bfd_window} to hold the contents of a section. This is 541called from @samp{bfd_get_section_contents_in_window}. The 542@samp{bfd_window} idea never really caught on, and I don't think this is 543ever called. Pretty much all targets implement this as 544@samp{bfd_generic_get_section_contents_in_window}, which uses 545@samp{bfd_get_section_contents} to do the right thing. The 546corresponding field in the target vector is named 547@samp{_bfd_get_section_contents_in_window}. 548@end table 549 550@node BFD target vector copy 551@subsection Copy functions 552@cindex @samp{BFD_JUMP_TABLE_COPY} 553 554The @samp{BFD_JUMP_TABLE_COPY} macro is used for functions which are 555called when copying BFDs, and for a couple of functions which deal with 556internal BFD information. 557 558@table @samp 559@item _bfd_copy_private_bfd_data 560This is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}. 561If the input and output BFDs have the same format, this will copy any 562private information over. This is called after all the section contents 563have been written to the output file. Only a few targets do anything in 564this function. 565 566@item _bfd_merge_private_bfd_data 567This is called when linking, via @samp{bfd_merge_private_bfd_data}. It 568gives the backend linker code a chance to set any special flags in the 569output file based on the contents of the input file. Only a few targets 570do anything in this function. 571 572@item _bfd_copy_private_section_data 573This is similar to @samp{_bfd_copy_private_bfd_data}, but it is called 574for each section, via @samp{bfd_copy_private_section_data}. This 575function is called before any section contents have been written. Only 576a few targets do anything in this function. 577 578@item _bfd_copy_private_symbol_data 579This is called via @samp{bfd_copy_private_symbol_data}, but I don't 580think anything actually calls it. If it were defined, it could be used 581to copy private symbol data from one BFD to another. However, most BFDs 582store extra symbol information by allocating space which is larger than 583the @samp{asymbol} structure and storing private information in the 584extra space. Since @samp{objcopy} and other programs copy symbol 585information by copying pointers to @samp{asymbol} structures, the 586private symbol information is automatically copied as well. Most 587targets do not do anything in this function. 588 589@item _bfd_set_private_flags 590This is called via @samp{bfd_set_private_flags}. It is basically a hook 591for the assembler to set magic information. For example, the PowerPC 592ELF assembler uses it to set flags which appear in the e_flags field of 593the ELF header. Most targets do not do anything in this function. 594 595@item _bfd_print_private_bfd_data 596This is called by @samp{objdump} when the @samp{-p} option is used. It 597is called via @samp{bfd_print_private_data}. It prints any interesting 598information about the BFD which can not be otherwise represented by BFD 599and thus can not be printed by @samp{objdump}. Most targets do not do 600anything in this function. 601@end table 602 603@node BFD target vector core 604@subsection Core file support functions 605@cindex @samp{BFD_JUMP_TABLE_CORE} 606 607The @samp{BFD_JUMP_TABLE_CORE} macro is used for functions which deal 608with core files. Obviously, these functions only do something 609interesting for targets which have core file support. 610 611@table @samp 612@item _core_file_failing_command 613Given a core file, this returns the command which was run to produce the 614core file. 615 616@item _core_file_failing_signal 617Given a core file, this returns the signal number which produced the 618core file. 619 620@item _core_file_matches_executable_p 621Given a core file and a BFD for an executable, this returns whether the 622core file was generated by the executable. 623@end table 624 625@node BFD target vector archive 626@subsection Archive functions 627@cindex @samp{BFD_JUMP_TABLE_ARCHIVE} 628 629The @samp{BFD_JUMP_TABLE_ARCHIVE} macro is used for functions which deal 630with archive files. Most targets use COFF style archive files 631(including ELF targets), and these use @samp{_bfd_archive_coff} as the 632argument to @samp{BFD_JUMP_TABLE_ARCHIVE}. Some targets use BSD/a.out 633style archives, and these use @samp{_bfd_archive_bsd}. (The main 634difference between BSD and COFF archives is the format of the archive 635symbol table). Targets with no archive support use 636@samp{_bfd_noarchive}. Finally, a few targets have unusual archive 637handling. 638 639@table @samp 640@item _slurp_armap 641Read in the archive symbol table, storing it in private BFD data. This 642is normally called from the archive @samp{check_format} routine. The 643corresponding field in the target vector is named 644@samp{_bfd_slurp_armap}. 645 646@item _slurp_extended_name_table 647Read in the extended name table from the archive, if there is one, 648storing it in private BFD data. This is normally called from the 649archive @samp{check_format} routine. The corresponding field in the 650target vector is named @samp{_bfd_slurp_extended_name_table}. 651 652@item construct_extended_name_table 653Build and return an extended name table if one is needed to write out 654the archive. This also adjusts the archive headers to refer to the 655extended name table appropriately. This is normally called from the 656archive @samp{write_contents} routine. The corresponding field in the 657target vector is named @samp{_bfd_construct_extended_name_table}. 658 659@item _truncate_arname 660This copies a file name into an archive header, truncating it as 661required. It is normally called from the archive @samp{write_contents} 662routine. This function is more interesting in targets which do not 663support extended name tables, but I think the GNU @samp{ar} program 664always uses extended name tables anyhow. The corresponding field in the 665target vector is named @samp{_bfd_truncate_arname}. 666 667@item _write_armap 668Write out the archive symbol table using calls to @samp{bfd_bwrite}. 669This is normally called from the archive @samp{write_contents} routine. 670The corresponding field in the target vector is named @samp{write_armap} 671(no leading underscore). 672 673@item _read_ar_hdr 674Read and parse an archive header. This handles expanding the archive 675header name into the real file name using the extended name table. This 676is called by routines which read the archive symbol table or the archive 677itself. The corresponding field in the target vector is named 678@samp{_bfd_read_ar_hdr_fn}. 679 680@item _openr_next_archived_file 681Given an archive and a BFD representing a file stored within the 682archive, return a BFD for the next file in the archive. This is called 683via @samp{bfd_openr_next_archived_file}. The corresponding field in the 684target vector is named @samp{openr_next_archived_file} (no leading 685underscore). 686 687@item _get_elt_at_index 688Given an archive and an index, return a BFD for the file in the archive 689corresponding to that entry in the archive symbol table. This is called 690via @samp{bfd_get_elt_at_index}. The corresponding field in the target 691vector is named @samp{_bfd_get_elt_at_index}. 692 693@item _generic_stat_arch_elt 694Do a stat on an element of an archive, returning information read from 695the archive header (modification time, uid, gid, file mode, size). This 696is called via @samp{bfd_stat_arch_elt}. The corresponding field in the 697target vector is named @samp{_bfd_stat_arch_elt}. 698 699@item _update_armap_timestamp 700After the entire contents of an archive have been written out, update 701the timestamp of the archive symbol table to be newer than that of the 702file. This is required for a.out style archives. This is normally 703called by the archive @samp{write_contents} routine. The corresponding 704field in the target vector is named @samp{_bfd_update_armap_timestamp}. 705@end table 706 707@node BFD target vector symbols 708@subsection Symbol table functions 709@cindex @samp{BFD_JUMP_TABLE_SYMBOLS} 710 711The @samp{BFD_JUMP_TABLE_SYMBOLS} macro is used for functions which deal 712with symbols. 713 714@table @samp 715@item _get_symtab_upper_bound 716Return a sensible upper bound on the amount of memory which will be 717required to read the symbol table. In practice most targets return the 718amount of memory required to hold @samp{asymbol} pointers for all the 719symbols plus a trailing @samp{NULL} entry, and store the actual symbol 720information in BFD private data. This is called via 721@samp{bfd_get_symtab_upper_bound}. The corresponding field in the 722target vector is named @samp{_bfd_get_symtab_upper_bound}. 723 724@item _canonicalize_symtab 725Read in the symbol table. This is called via 726@samp{bfd_canonicalize_symtab}. The corresponding field in the target 727vector is named @samp{_bfd_canonicalize_symtab}. 728 729@item _make_empty_symbol 730Create an empty symbol for the BFD. This is needed because most targets 731store extra information with each symbol by allocating a structure 732larger than an @samp{asymbol} and storing the extra information at the 733end. This function will allocate the right amount of memory, and return 734what looks like a pointer to an empty @samp{asymbol}. This is called 735via @samp{bfd_make_empty_symbol}. The corresponding field in the target 736vector is named @samp{_bfd_make_empty_symbol}. 737 738@item _print_symbol 739Print information about the symbol. This is called via 740@samp{bfd_print_symbol}. One of the arguments indicates what sort of 741information should be printed: 742 743@table @samp 744@item bfd_print_symbol_name 745Just print the symbol name. 746@item bfd_print_symbol_more 747Print the symbol name and some interesting flags. I don't think 748anything actually uses this. 749@item bfd_print_symbol_all 750Print all information about the symbol. This is used by @samp{objdump} 751when run with the @samp{-t} option. 752@end table 753The corresponding field in the target vector is named 754@samp{_bfd_print_symbol}. 755 756@item _get_symbol_info 757Return a standard set of information about the symbol. This is called 758via @samp{bfd_symbol_info}. The corresponding field in the target 759vector is named @samp{_bfd_get_symbol_info}. 760 761@item _bfd_is_local_label_name 762Return whether the given string would normally represent the name of a 763local label. This is called via @samp{bfd_is_local_label} and 764@samp{bfd_is_local_label_name}. Local labels are normally discarded by 765the assembler. In the linker, this defines the difference between the 766@samp{-x} and @samp{-X} options. 767 768@item _get_lineno 769Return line number information for a symbol. This is only meaningful 770for a COFF target. This is called when writing out COFF line numbers. 771 772@item _find_nearest_line 773Given an address within a section, use the debugging information to find 774the matching file name, function name, and line number, if any. This is 775called via @samp{bfd_find_nearest_line}. The corresponding field in the 776target vector is named @samp{_bfd_find_nearest_line}. 777 778@item _bfd_make_debug_symbol 779Make a debugging symbol. This is only meaningful for a COFF target, 780where it simply returns a symbol which will be placed in the 781@samp{N_DEBUG} section when it is written out. This is called via 782@samp{bfd_make_debug_symbol}. 783 784@item _read_minisymbols 785Minisymbols are used to reduce the memory requirements of programs like 786@samp{nm}. A minisymbol is a cookie pointing to internal symbol 787information which the caller can use to extract complete symbol 788information. This permits BFD to not convert all the symbols into 789generic form, but to instead convert them one at a time. This is called 790via @samp{bfd_read_minisymbols}. Most targets do not implement this, 791and just use generic support which is based on using standard 792@samp{asymbol} structures. 793 794@item _minisymbol_to_symbol 795Convert a minisymbol to a standard @samp{asymbol}. This is called via 796@samp{bfd_minisymbol_to_symbol}. 797@end table 798 799@node BFD target vector relocs 800@subsection Relocation support 801@cindex @samp{BFD_JUMP_TABLE_RELOCS} 802 803The @samp{BFD_JUMP_TABLE_RELOCS} macro is used for functions which deal 804with relocations. 805 806@table @samp 807@item _get_reloc_upper_bound 808Return a sensible upper bound on the amount of memory which will be 809required to read the relocations for a section. In practice most 810targets return the amount of memory required to hold @samp{arelent} 811pointers for all the relocations plus a trailing @samp{NULL} entry, and 812store the actual relocation information in BFD private data. This is 813called via @samp{bfd_get_reloc_upper_bound}. 814 815@item _canonicalize_reloc 816Return the relocation information for a section. This is called via 817@samp{bfd_canonicalize_reloc}. The corresponding field in the target 818vector is named @samp{_bfd_canonicalize_reloc}. 819 820@item _bfd_reloc_type_lookup 821Given a relocation code, return the corresponding howto structure 822(@pxref{BFD relocation codes}). This is called via 823@samp{bfd_reloc_type_lookup}. The corresponding field in the target 824vector is named @samp{reloc_type_lookup}. 825@end table 826 827@node BFD target vector write 828@subsection Output functions 829@cindex @samp{BFD_JUMP_TABLE_WRITE} 830 831The @samp{BFD_JUMP_TABLE_WRITE} macro is used for functions which deal 832with writing out a BFD. 833 834@table @samp 835@item _set_arch_mach 836Set the architecture and machine number for a BFD. This is called via 837@samp{bfd_set_arch_mach}. Most targets implement this by calling 838@samp{bfd_default_set_arch_mach}. The corresponding field in the target 839vector is named @samp{_bfd_set_arch_mach}. 840 841@item _set_section_contents 842Write out the contents of a section. This is called via 843@samp{bfd_set_section_contents}. The corresponding field in the target 844vector is named @samp{_bfd_set_section_contents}. 845@end table 846 847@node BFD target vector link 848@subsection Linker functions 849@cindex @samp{BFD_JUMP_TABLE_LINK} 850 851The @samp{BFD_JUMP_TABLE_LINK} macro is used for functions called by the 852linker. 853 854@table @samp 855@item _sizeof_headers 856Return the size of the header information required for a BFD. This is 857used to implement the @samp{SIZEOF_HEADERS} linker script function. It 858is normally used to align the first section at an efficient position on 859the page. This is called via @samp{bfd_sizeof_headers}. The 860corresponding field in the target vector is named 861@samp{_bfd_sizeof_headers}. 862 863@item _bfd_get_relocated_section_contents 864Read the contents of a section and apply the relocation information. 865This handles both a final link and a relocatable link; in the latter 866case, it adjust the relocation information as well. This is called via 867@samp{bfd_get_relocated_section_contents}. Most targets implement it by 868calling @samp{bfd_generic_get_relocated_section_contents}. 869 870@item _bfd_relax_section 871Try to use relaxation to shrink the size of a section. This is called 872by the linker when the @samp{-relax} option is used. This is called via 873@samp{bfd_relax_section}. Most targets do not support any sort of 874relaxation. 875 876@item _bfd_link_hash_table_create 877Create the symbol hash table to use for the linker. This linker hook 878permits the backend to control the size and information of the elements 879in the linker symbol hash table. This is called via 880@samp{bfd_link_hash_table_create}. 881 882@item _bfd_link_add_symbols 883Given an object file or an archive, add all symbols into the linker 884symbol hash table. Use callbacks to the linker to include archive 885elements in the link. This is called via @samp{bfd_link_add_symbols}. 886 887@item _bfd_final_link 888Finish the linking process. The linker calls this hook after all of the 889input files have been read, when it is ready to finish the link and 890generate the output file. This is called via @samp{bfd_final_link}. 891 892@item _bfd_link_split_section 893I don't know what this is for. Nothing seems to call it. The only 894non-trivial definition is in @file{som.c}. 895@end table 896 897@node BFD target vector dynamic 898@subsection Dynamic linking information functions 899@cindex @samp{BFD_JUMP_TABLE_DYNAMIC} 900 901The @samp{BFD_JUMP_TABLE_DYNAMIC} macro is used for functions which read 902dynamic linking information. 903 904@table @samp 905@item _get_dynamic_symtab_upper_bound 906Return a sensible upper bound on the amount of memory which will be 907required to read the dynamic symbol table. In practice most targets 908return the amount of memory required to hold @samp{asymbol} pointers for 909all the symbols plus a trailing @samp{NULL} entry, and store the actual 910symbol information in BFD private data. This is called via 911@samp{bfd_get_dynamic_symtab_upper_bound}. The corresponding field in 912the target vector is named @samp{_bfd_get_dynamic_symtab_upper_bound}. 913 914@item _canonicalize_dynamic_symtab 915Read the dynamic symbol table. This is called via 916@samp{bfd_canonicalize_dynamic_symtab}. The corresponding field in the 917target vector is named @samp{_bfd_canonicalize_dynamic_symtab}. 918 919@item _get_dynamic_reloc_upper_bound 920Return a sensible upper bound on the amount of memory which will be 921required to read the dynamic relocations. In practice most targets 922return the amount of memory required to hold @samp{arelent} pointers for 923all the relocations plus a trailing @samp{NULL} entry, and store the 924actual relocation information in BFD private data. This is called via 925@samp{bfd_get_dynamic_reloc_upper_bound}. The corresponding field in 926the target vector is named @samp{_bfd_get_dynamic_reloc_upper_bound}. 927 928@item _canonicalize_dynamic_reloc 929Read the dynamic relocations. This is called via 930@samp{bfd_canonicalize_dynamic_reloc}. The corresponding field in the 931target vector is named @samp{_bfd_canonicalize_dynamic_reloc}. 932@end table 933 934@node BFD generated files 935@section BFD generated files 936@cindex generated files in bfd 937@cindex bfd generated files 938 939BFD contains several automatically generated files. This section 940describes them. Some files are created at configure time, when you 941configure BFD. Some files are created at make time, when you build 942BFD. Some files are automatically rebuilt at make time, but only if 943you configure with the @samp{--enable-maintainer-mode} option. Some 944files live in the object directory---the directory from which you run 945configure---and some live in the source directory. All files that live 946in the source directory are checked into the CVS repository. 947 948@table @file 949@item bfd.h 950@cindex @file{bfd.h} 951@cindex @file{bfd-in3.h} 952Lives in the object directory. Created at make time from 953@file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at 954configure time from @file{bfd-in2.h}. There are automatic dependencies 955to rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h} 956changes, so you can normally ignore @file{bfd-in3.h}, and just think 957about @file{bfd-in2.h} and @file{bfd.h}. 958 959@file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}. 960To see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly 961control whether BFD is built for a 32 bit target or a 64 bit target. 962 963@item bfd-in2.h 964@cindex @file{bfd-in2.h} 965Lives in the source directory. Created from @file{bfd-in.h} and several 966other BFD source files. If you configure with the 967@samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt 968automatically when a source file changes. 969 970@item elf32-target.h 971@itemx elf64-target.h 972@cindex @file{elf32-target.h} 973@cindex @file{elf64-target.h} 974Live in the object directory. Created from @file{elfxx-target.h}. 975These files are versions of @file{elfxx-target.h} customized for either 976a 32 bit ELF target or a 64 bit ELF target. 977 978@item libbfd.h 979@cindex @file{libbfd.h} 980Lives in the source directory. Created from @file{libbfd-in.h} and 981several other BFD source files. If you configure with the 982@samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt 983automatically when a source file changes. 984 985@item libcoff.h 986@cindex @file{libcoff.h} 987Lives in the source directory. Created from @file{libcoff-in.h} and 988@file{coffcode.h}. If you configure with the 989@samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt 990automatically when a source file changes. 991 992@item targmatch.h 993@cindex @file{targmatch.h} 994Lives in the object directory. Created at make time from 995@file{config.bfd}. This file is used to map configuration triplets into 996BFD target vector variable names at run time. 997@end table 998 999@node BFD multiple compilations 1000@section Files compiled multiple times in BFD 1001Several files in BFD are compiled multiple times. By this I mean that 1002there are header files which contain function definitions. These header 1003files are included by other files, and thus the functions are compiled 1004once per file which includes them. 1005 1006Preprocessor macros are used to control the compilation, so that each 1007time the files are compiled the resulting functions are slightly 1008different. Naturally, if they weren't different, there would be no 1009reason to compile them multiple times. 1010 1011This is a not a particularly good programming technique, and future BFD 1012work should avoid it. 1013 1014@itemize @bullet 1015@item 1016Since this technique is rarely used, even experienced C programmers find 1017it confusing. 1018 1019@item 1020It is difficult to debug programs which use BFD, since there is no way 1021to describe which version of a particular function you are looking at. 1022 1023@item 1024Programs which use BFD wind up incorporating two or more slightly 1025different versions of the same function, which wastes space in the 1026executable. 1027 1028@item 1029This technique is never required nor is it especially efficient. It is 1030always possible to use statically initialized structures holding 1031function pointers and magic constants instead. 1032@end itemize 1033 1034The following is a list of the files which are compiled multiple times. 1035 1036@table @file 1037@item aout-target.h 1038@cindex @file{aout-target.h} 1039Describes a few functions and the target vector for a.out targets. This 1040is used by individual a.out targets with different definitions of 1041@samp{N_TXTADDR} and similar a.out macros. 1042 1043@item aoutf1.h 1044@cindex @file{aoutf1.h} 1045Implements standard SunOS a.out files. In principle it supports 64 bit 1046a.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but 1047since all known a.out targets are 32 bits, this code may or may not 1048work. This file is only included by a few other files, and it is 1049difficult to justify its existence. 1050 1051@item aoutx.h 1052@cindex @file{aoutx.h} 1053Implements basic a.out support routines. This file can be compiled for 1054either 32 or 64 bit support. Since all known a.out targets are 32 bits, 1055the 64 bit support may or may not work. I believe the original 1056intention was that this file would only be included by @samp{aout32.c} 1057and @samp{aout64.c}, and that other a.out targets would simply refer to 1058the functions it defined. Unfortunately, some other a.out targets 1059started including it directly, leading to a somewhat confused state of 1060affairs. 1061 1062@item coffcode.h 1063@cindex @file{coffcode.h} 1064Implements basic COFF support routines. This file is included by every 1065COFF target. It implements code which handles COFF magic numbers as 1066well as various hook functions called by the generic COFF functions in 1067@file{coffgen.c}. This file is controlled by a number of different 1068macros, and more are added regularly. 1069 1070@item coffswap.h 1071@cindex @file{coffswap.h} 1072Implements COFF swapping routines. This file is included by 1073@file{coffcode.h}, and thus by every COFF target. It implements the 1074routines which swap COFF structures between internal and external 1075format. The main control for this file is the external structure 1076definitions in the files in the @file{include/coff} directory. A COFF 1077target file will include one of those files before including 1078@file{coffcode.h} and thus @file{coffswap.h}. There are a few other 1079macros which affect @file{coffswap.h} as well, mostly describing whether 1080certain fields are present in the external structures. 1081 1082@item ecoffswap.h 1083@cindex @file{ecoffswap.h} 1084Implements ECOFF swapping routines. This is like @file{coffswap.h}, but 1085for ECOFF. It is included by the ECOFF target files (of which there are 1086only two). The control is the preprocessor macro @samp{ECOFF_32} or 1087@samp{ECOFF_64}. 1088 1089@item elfcode.h 1090@cindex @file{elfcode.h} 1091Implements ELF functions that use external structure definitions. This 1092file is included by two other files: @file{elf32.c} and @file{elf64.c}. 1093It is controlled by the @samp{ARCH_SIZE} macro which is defined to be 1094@samp{32} or @samp{64} before including it. The @samp{NAME} macro is 1095used internally to give the functions different names for the two target 1096sizes. 1097 1098@item elfcore.h 1099@cindex @file{elfcore.h} 1100Like @file{elfcode.h}, but for functions that are specific to ELF core 1101files. This is included only by @file{elfcode.h}. 1102 1103@item elfxx-target.h 1104@cindex @file{elfxx-target.h} 1105This file is the source for the generated files @file{elf32-target.h} 1106and @file{elf64-target.h}, one of which is included by every ELF target. 1107It defines the ELF target vector. 1108 1109@item freebsd.h 1110@cindex @file{freebsd.h} 1111Presumably intended to be included by all FreeBSD targets, but in fact 1112there is only one such target, @samp{i386-freebsd}. This defines a 1113function used to set the right magic number for FreeBSD, as well as 1114various macros, and includes @file{aout-target.h}. 1115 1116@item netbsd.h 1117@cindex @file{netbsd.h} 1118Like @file{freebsd.h}, except that there are several files which include 1119it. 1120 1121@item nlm-target.h 1122@cindex @file{nlm-target.h} 1123Defines the target vector for a standard NLM target. 1124 1125@item nlmcode.h 1126@cindex @file{nlmcode.h} 1127Like @file{elfcode.h}, but for NLM targets. This is only included by 1128@file{nlm32.c} and @file{nlm64.c}, both of which define the macro 1129@samp{ARCH_SIZE} to an appropriate value. There are no 64 bit NLM 1130targets anyhow, so this is sort of useless. 1131 1132@item nlmswap.h 1133@cindex @file{nlmswap.h} 1134Like @file{coffswap.h}, but for NLM targets. This is included by each 1135NLM target, but I think it winds up compiling to the exact same code for 1136every target, and as such is fairly useless. 1137 1138@item peicode.h 1139@cindex @file{peicode.h} 1140Provides swapping routines and other hooks for PE targets. 1141@file{coffcode.h} will include this rather than @file{coffswap.h} for a 1142PE target. This defines PE specific versions of the COFF swapping 1143routines, and also defines some macros which control @file{coffcode.h} 1144itself. 1145@end table 1146 1147@node BFD relocation handling 1148@section BFD relocation handling 1149@cindex bfd relocation handling 1150@cindex relocations in bfd 1151 1152The handling of relocations is one of the more confusing aspects of BFD. 1153Relocation handling has been implemented in various different ways, all 1154somewhat incompatible, none perfect. 1155 1156@menu 1157* BFD relocation concepts:: BFD relocation concepts 1158* BFD relocation functions:: BFD relocation functions 1159* BFD relocation codes:: BFD relocation codes 1160* BFD relocation future:: BFD relocation future 1161@end menu 1162 1163@node BFD relocation concepts 1164@subsection BFD relocation concepts 1165 1166A relocation is an action which the linker must take when linking. It 1167describes a change to the contents of a section. The change is normally 1168based on the final value of one or more symbols. Relocations are 1169created by the assembler when it creates an object file. 1170 1171Most relocations are simple. A typical simple relocation is to set 32 1172bits at a given offset in a section to the value of a symbol. This type 1173of relocation would be generated for code like @code{int *p = &i;} where 1174@samp{p} and @samp{i} are global variables. A relocation for the symbol 1175@samp{i} would be generated such that the linker would initialize the 1176area of memory which holds the value of @samp{p} to the value of the 1177symbol @samp{i}. 1178 1179Slightly more complex relocations may include an addend, which is a 1180constant to add to the symbol value before using it. In some cases a 1181relocation will require adding the symbol value to the existing contents 1182of the section in the object file. In others the relocation will simply 1183replace the contents of the section with the symbol value. Some 1184relocations are PC relative, so that the value to be stored in the 1185section is the difference between the value of a symbol and the final 1186address of the section contents. 1187 1188In general, relocations can be arbitrarily complex. For example, 1189relocations used in dynamic linking systems often require the linker to 1190allocate space in a different section and use the offset within that 1191section as the value to store. In the IEEE object file format, 1192relocations may involve arbitrary expressions. 1193 1194When doing a relocatable link, the linker may or may not have to do 1195anything with a relocation, depending upon the definition of the 1196relocation. Simple relocations generally do not require any special 1197action. 1198 1199@node BFD relocation functions 1200@subsection BFD relocation functions 1201 1202In BFD, each section has an array of @samp{arelent} structures. Each 1203structure has a pointer to a symbol, an address within the section, an 1204addend, and a pointer to a @samp{reloc_howto_struct} structure. The 1205howto structure has a bunch of fields describing the reloc, including a 1206type field. The type field is specific to the object file format 1207backend; none of the generic code in BFD examines it. 1208 1209Originally, the function @samp{bfd_perform_relocation} was supposed to 1210handle all relocations. In theory, many relocations would be simple 1211enough to be described by the fields in the howto structure. For those 1212that weren't, the howto structure included a @samp{special_function} 1213field to use as an escape. 1214 1215While this seems plausible, a look at @samp{bfd_perform_relocation} 1216shows that it failed. The function has odd special cases. Some of the 1217fields in the howto structure, such as @samp{pcrel_offset}, were not 1218adequately documented. 1219 1220The linker uses @samp{bfd_perform_relocation} to do all relocations when 1221the input and output file have different formats (e.g., when generating 1222S-records). The generic linker code, which is used by all targets which 1223do not define their own special purpose linker, uses 1224@samp{bfd_get_relocated_section_contents}, which for most targets turns 1225into a call to @samp{bfd_generic_get_relocated_section_contents}, which 1226calls @samp{bfd_perform_relocation}. So @samp{bfd_perform_relocation} 1227is still widely used, which makes it difficult to change, since it is 1228difficult to test all possible cases. 1229 1230The assembler used @samp{bfd_perform_relocation} for a while. This 1231turned out to be the wrong thing to do, since 1232@samp{bfd_perform_relocation} was written to handle relocations on an 1233existing object file, while the assembler needed to create relocations 1234in a new object file. The assembler was changed to use the new function 1235@samp{bfd_install_relocation} instead, and @samp{bfd_install_relocation} 1236was created as a copy of @samp{bfd_perform_relocation}. 1237 1238Unfortunately, the work did not progress any farther, so 1239@samp{bfd_install_relocation} remains a simple copy of 1240@samp{bfd_perform_relocation}, with all the odd special cases and 1241confusing code. This again is difficult to change, because again any 1242change can affect any assembler target, and so is difficult to test. 1243 1244The new linker, when using the same object file format for all input 1245files and the output file, does not convert relocations into 1246@samp{arelent} structures, so it can not use 1247@samp{bfd_perform_relocation} at all. Instead, users of the new linker 1248are expected to write a @samp{relocate_section} function which will 1249handle relocations in a target specific fashion. 1250 1251There are two helper functions for target specific relocation: 1252@samp{_bfd_final_link_relocate} and @samp{_bfd_relocate_contents}. 1253These functions use a howto structure, but they @emph{do not} use the 1254@samp{special_function} field. Since the functions are normally called 1255from target specific code, the @samp{special_function} field adds 1256little; any relocations which require special handling can be handled 1257without calling those functions. 1258 1259So, if you want to add a new target, or add a new relocation to an 1260existing target, you need to do the following: 1261 1262@itemize @bullet 1263@item 1264Make sure you clearly understand what the contents of the section should 1265look like after assembly, after a relocatable link, and after a final 1266link. Make sure you clearly understand the operations the linker must 1267perform during a relocatable link and during a final link. 1268 1269@item 1270Write a howto structure for the relocation. The howto structure is 1271flexible enough to represent any relocation which should be handled by 1272setting a contiguous bitfield in the destination to the value of a 1273symbol, possibly with an addend, possibly adding the symbol value to the 1274value already present in the destination. 1275 1276@item 1277Change the assembler to generate your relocation. The assembler will 1278call @samp{bfd_install_relocation}, so your howto structure has to be 1279able to handle that. You may need to set the @samp{special_function} 1280field to handle assembly correctly. Be careful to ensure that any code 1281you write to handle the assembler will also work correctly when doing a 1282relocatable link. For example, see @samp{bfd_elf_generic_reloc}. 1283 1284@item 1285Test the assembler. Consider the cases of relocation against an 1286undefined symbol, a common symbol, a symbol defined in the object file 1287in the same section, and a symbol defined in the object file in a 1288different section. These cases may not all be applicable for your 1289reloc. 1290 1291@item 1292If your target uses the new linker, which is recommended, add any 1293required handling to the target specific relocation function. In simple 1294cases this will just involve a call to @samp{_bfd_final_link_relocate} 1295or @samp{_bfd_relocate_contents}, depending upon the definition of the 1296relocation and whether the link is relocatable or not. 1297 1298@item 1299Test the linker. Test the case of a final link. If the relocation can 1300overflow, use a linker script to force an overflow and make sure the 1301error is reported correctly. Test a relocatable link, whether the 1302symbol is defined or undefined in the relocatable output. For both the 1303final and relocatable link, test the case when the symbol is a common 1304symbol, when the symbol looked like a common symbol but became a defined 1305symbol, when the symbol is defined in a different object file, and when 1306the symbol is defined in the same object file. 1307 1308@item 1309In order for linking to another object file format, such as S-records, 1310to work correctly, @samp{bfd_perform_relocation} has to do the right 1311thing for the relocation. You may need to set the 1312@samp{special_function} field to handle this correctly. Test this by 1313doing a link in which the output object file format is S-records. 1314 1315@item 1316Using the linker to generate relocatable output in a different object 1317file format is impossible in the general case, so you generally don't 1318have to worry about that. The GNU linker makes sure to stop that from 1319happening when an input file in a different format has relocations. 1320 1321Linking input files of different object file formats together is quite 1322unusual, but if you're really dedicated you may want to consider testing 1323this case, both when the output object file format is the same as your 1324format, and when it is different. 1325@end itemize 1326 1327@node BFD relocation codes 1328@subsection BFD relocation codes 1329 1330BFD has another way of describing relocations besides the howto 1331structures described above: the enum @samp{bfd_reloc_code_real_type}. 1332 1333Every known relocation type can be described as a value in this 1334enumeration. The enumeration contains many target specific relocations, 1335but where two or more targets have the same relocation, a single code is 1336used. For example, the single value @samp{BFD_RELOC_32} is used for all 1337simple 32 bit relocation types. 1338 1339The main purpose of this relocation code is to give the assembler some 1340mechanism to create @samp{arelent} structures. In order for the 1341assembler to create an @samp{arelent} structure, it has to be able to 1342obtain a howto structure. The function @samp{bfd_reloc_type_lookup}, 1343which simply calls the target vector entry point 1344@samp{reloc_type_lookup}, takes a relocation code and returns a howto 1345structure. 1346 1347The function @samp{bfd_get_reloc_code_name} returns the name of a 1348relocation code. This is mainly used in error messages. 1349 1350Using both howto structures and relocation codes can be somewhat 1351confusing. There are many processor specific relocation codes. 1352However, the relocation is only fully defined by the howto structure. 1353The same relocation code will map to different howto structures in 1354different object file formats. For example, the addend handling may be 1355different. 1356 1357Most of the relocation codes are not really general. The assembler can 1358not use them without already understanding what sorts of relocations can 1359be used for a particular target. It might be possible to replace the 1360relocation codes with something simpler. 1361 1362@node BFD relocation future 1363@subsection BFD relocation future 1364 1365Clearly the current BFD relocation support is in bad shape. A 1366wholescale rewrite would be very difficult, because it would require 1367thorough testing of every BFD target. So some sort of incremental 1368change is required. 1369 1370My vague thoughts on this would involve defining a new, clearly defined, 1371howto structure. Some mechanism would be used to determine which type 1372of howto structure was being used by a particular format. 1373 1374The new howto structure would clearly define the relocation behaviour in 1375the case of an assembly, a relocatable link, and a final link. At 1376least one special function would be defined as an escape, and it might 1377make sense to define more. 1378 1379One or more generic functions similar to @samp{bfd_perform_relocation} 1380would be written to handle the new howto structure. 1381 1382This should make it possible to write a generic version of the relocate 1383section functions used by the new linker. The target specific code 1384would provide some mechanism (a function pointer or an initial 1385conversion) to convert target specific relocations into howto 1386structures. 1387 1388Ideally it would be possible to use this generic relocate section 1389function for the generic linker as well. That is, it would replace the 1390@samp{bfd_generic_get_relocated_section_contents} function which is 1391currently normally used. 1392 1393For the special case of ELF dynamic linking, more consideration needs to 1394be given to writing ELF specific but ELF target generic code to handle 1395special relocation types such as GOT and PLT. 1396 1397@node BFD ELF support 1398@section BFD ELF support 1399@cindex elf support in bfd 1400@cindex bfd elf support 1401 1402The ELF object file format is defined in two parts: a generic ABI and a 1403processor specific supplement. The ELF support in BFD is split in a 1404similar fashion. The processor specific support is largely kept within 1405a single file. The generic support is provided by several other files. 1406The processor specific support provides a set of function pointers and 1407constants used by the generic support. 1408 1409@menu 1410* BFD ELF sections and segments:: ELF sections and segments 1411* BFD ELF generic support:: BFD ELF generic support 1412* BFD ELF processor specific support:: BFD ELF processor specific support 1413* BFD ELF core files:: BFD ELF core files 1414* BFD ELF future:: BFD ELF future 1415@end menu 1416 1417@node BFD ELF sections and segments 1418@subsection ELF sections and segments 1419 1420The ELF ABI permits a file to have either sections or segments or both. 1421Relocatable object files conventionally have only sections. 1422Executables conventionally have both. Core files conventionally have 1423only program segments. 1424 1425ELF sections are similar to sections in other object file formats: they 1426have a name, a VMA, file contents, flags, and other miscellaneous 1427information. ELF relocations are stored in sections of a particular 1428type; BFD automatically converts these sections into internal relocation 1429information. 1430 1431ELF program segments are intended for fast interpretation by a system 1432loader. They have a type, a VMA, an LMA, file contents, and a couple of 1433other fields. When an ELF executable is run on a Unix system, the 1434system loader will examine the program segments to decide how to load 1435it. The loader will ignore the section information. Loadable program 1436segments (type @samp{PT_LOAD}) are directly loaded into memory. Other 1437program segments are interpreted by the loader, and generally provide 1438dynamic linking information. 1439 1440When an ELF file has both program segments and sections, an ELF program 1441segment may encompass one or more ELF sections, in the sense that the 1442portion of the file which corresponds to the program segment may include 1443the portions of the file corresponding to one or more sections. When 1444there is more than one section in a loadable program segment, the 1445relative positions of the section contents in the file must correspond 1446to the relative positions they should hold when the program segment is 1447loaded. This requirement should be obvious if you consider that the 1448system loader will load an entire program segment at a time. 1449 1450On a system which supports dynamic paging, such as any native Unix 1451system, the contents of a loadable program segment must be at the same 1452offset in the file as in memory, modulo the memory page size used on the 1453system. This is because the system loader will map the file into memory 1454starting at the start of a page. The system loader can easily remap 1455entire pages to the correct load address. However, if the contents of 1456the file were not correctly aligned within the page, the system loader 1457would have to shift the contents around within the page, which is too 1458expensive. For example, if the LMA of a loadable program segment is 1459@samp{0x40080} and the page size is @samp{0x1000}, then the position of 1460the segment contents within the file must equal @samp{0x80} modulo 1461@samp{0x1000}. 1462 1463BFD has only a single set of sections. It does not provide any generic 1464way to examine both sections and segments. When BFD is used to open an 1465object file or executable, the BFD sections will represent ELF sections. 1466When BFD is used to open a core file, the BFD sections will represent 1467ELF program segments. 1468 1469When BFD is used to examine an object file or executable, any program 1470segments will be read to set the LMA of the sections. This is because 1471ELF sections only have a VMA, while ELF program segments have both a VMA 1472and an LMA. Any program segments will be copied by the 1473@samp{copy_private} entry points. They will be printed by the 1474@samp{print_private} entry point. Otherwise, the program segments are 1475ignored. In particular, programs which use BFD currently have no direct 1476access to the program segments. 1477 1478When BFD is used to create an executable, the program segments will be 1479created automatically based on the section information. This is done in 1480the function @samp{assign_file_positions_for_segments} in @file{elf.c}. 1481This function has been tweaked many times, and probably still has 1482problems that arise in particular cases. 1483 1484There is a hook which may be used to explicitly define the program 1485segments when creating an executable: the @samp{bfd_record_phdr} 1486function in @file{bfd.c}. If this function is called, BFD will not 1487create program segments itself, but will only create the program 1488segments specified by the caller. The linker uses this function to 1489implement the @samp{PHDRS} linker script command. 1490 1491@node BFD ELF generic support 1492@subsection BFD ELF generic support 1493 1494In general, functions which do not read external data from the ELF file 1495are found in @file{elf.c}. They operate on the internal forms of the 1496ELF structures, which are defined in @file{include/elf/internal.h}. The 1497internal structures are defined in terms of @samp{bfd_vma}, and so may 1498be used for both 32 bit and 64 bit ELF targets. 1499 1500The file @file{elfcode.h} contains functions which operate on the 1501external data. @file{elfcode.h} is compiled twice, once via 1502@file{elf32.c} with @samp{ARCH_SIZE} defined as @samp{32}, and once via 1503@file{elf64.c} with @samp{ARCH_SIZE} defined as @samp{64}. 1504@file{elfcode.h} includes functions to swap the ELF structures in and 1505out of external form, as well as a few more complex functions. 1506 1507Linker support is found in @file{elflink.c}. The 1508linker support is only used if the processor specific file defines 1509@samp{elf_backend_relocate_section}, which is required to relocate the 1510section contents. If that macro is not defined, the generic linker code 1511is used, and relocations are handled via @samp{bfd_perform_relocation}. 1512 1513The core file support is in @file{elfcore.h}, which is compiled twice, 1514for both 32 and 64 bit support. The more interesting cases of core file 1515support only work on a native system which has the @file{sys/procfs.h} 1516header file. Without that file, the core file support does little more 1517than read the ELF program segments as BFD sections. 1518 1519The BFD internal header file @file{elf-bfd.h} is used for communication 1520among these files and the processor specific files. 1521 1522The default entries for the BFD ELF target vector are found mainly in 1523@file{elf.c}. Some functions are found in @file{elfcode.h}. 1524 1525The processor specific files may override particular entries in the 1526target vector, but most do not, with one exception: the 1527@samp{bfd_reloc_type_lookup} entry point is always processor specific. 1528 1529@node BFD ELF processor specific support 1530@subsection BFD ELF processor specific support 1531 1532By convention, the processor specific support for a particular processor 1533will be found in @file{elf@var{nn}-@var{cpu}.c}, where @var{nn} is 1534either 32 or 64, and @var{cpu} is the name of the processor. 1535 1536@menu 1537* BFD ELF processor required:: Required processor specific support 1538* BFD ELF processor linker:: Processor specific linker support 1539* BFD ELF processor other:: Other processor specific support options 1540@end menu 1541 1542@node BFD ELF processor required 1543@subsubsection Required processor specific support 1544 1545When writing a @file{elf@var{nn}-@var{cpu}.c} file, you must do the 1546following: 1547 1548@itemize @bullet 1549@item 1550Define either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or 1551both, to a unique C name to use for the target vector. This name should 1552appear in the list of target vectors in @file{targets.c}, and will also 1553have to appear in @file{config.bfd} and @file{configure.in}. Define 1554@samp{TARGET_BIG_SYM} for a big-endian processor, 1555@samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both 1556for a bi-endian processor. 1557@item 1558Define either @samp{TARGET_BIG_NAME} or @samp{TARGET_LITTLE_NAME}, or 1559both, to a string used as the name of the target vector. This is the 1560name which a user of the BFD tool would use to specify the object file 1561format. It would normally appear in a linker emulation parameters 1562file. 1563@item 1564Define @samp{ELF_ARCH} to the BFD architecture (an element of the 1565@samp{bfd_architecture} enum, typically @samp{bfd_arch_@var{cpu}}). 1566@item 1567Define @samp{ELF_MACHINE_CODE} to the magic number which should appear 1568in the @samp{e_machine} field of the ELF header. As of this writing, 1569these magic numbers are assigned by Caldera; if you want to get a magic 1570number for a particular processor, try sending a note to 1571@email{registry@@caldera.com}. In the BFD sources, the magic numbers are 1572found in @file{include/elf/common.h}; they have names beginning with 1573@samp{EM_}. 1574@item 1575Define @samp{ELF_MAXPAGESIZE} to the maximum size of a virtual page in 1576memory. This can normally be found at the start of chapter 5 in the 1577processor specific supplement. For a processor which will only be used 1578in an embedded system, or which has no memory management hardware, this 1579can simply be @samp{1}. 1580@item 1581If the format should use @samp{Rel} rather than @samp{Rela} relocations, 1582define @samp{USE_REL}. This is normally defined in chapter 4 of the 1583processor specific supplement. 1584 1585In the absence of a supplement, it's easier to work with @samp{Rela} 1586relocations. @samp{Rela} relocations will require more space in object 1587files (but not in executables, except when using dynamic linking). 1588However, this is outweighed by the simplicity of addend handling when 1589using @samp{Rela} relocations. With @samp{Rel} relocations, the addend 1590must be stored in the section contents, which makes relocatable links 1591more complex. 1592 1593For example, consider C code like @code{i = a[1000];} where @samp{a} is 1594a global array. The instructions which load the value of @samp{a[1000]} 1595will most likely use a relocation which refers to the symbol 1596representing @samp{a}, with an addend that gives the offset from the 1597start of @samp{a} to element @samp{1000}. When using @samp{Rel} 1598relocations, that addend must be stored in the instructions themselves. 1599If you are adding support for a RISC chip which uses two or more 1600instructions to load an address, then the addend may not fit in a single 1601instruction, and will have to be somehow split among the instructions. 1602This makes linking awkward, particularly when doing a relocatable link 1603in which the addend may have to be updated. It can be done---the MIPS 1604ELF support does it---but it should be avoided when possible. 1605 1606It is possible, though somewhat awkward, to support both @samp{Rel} and 1607@samp{Rela} relocations for a single target; @file{elf64-mips.c} does it 1608by overriding the relocation reading and writing routines. 1609@item 1610Define howto structures for all the relocation types. 1611@item 1612Define a @samp{bfd_reloc_type_lookup} routine. This must be named 1613@samp{bfd_elf@var{nn}_bfd_reloc_type_lookup}, and may be either a 1614function or a macro. It must translate a BFD relocation code into a 1615howto structure. This is normally a table lookup or a simple switch. 1616@item 1617If using @samp{Rel} relocations, define @samp{elf_info_to_howto_rel}. 1618If using @samp{Rela} relocations, define @samp{elf_info_to_howto}. 1619Either way, this is a macro defined as the name of a function which 1620takes an @samp{arelent} and a @samp{Rel} or @samp{Rela} structure, and 1621sets the @samp{howto} field of the @samp{arelent} based on the 1622@samp{Rel} or @samp{Rela} structure. This is normally uses 1623@samp{ELF@var{nn}_R_TYPE} to get the ELF relocation type and uses it as 1624an index into a table of howto structures. 1625@end itemize 1626 1627You must also add the magic number for this processor to the 1628@samp{prep_headers} function in @file{elf.c}. 1629 1630You must also create a header file in the @file{include/elf} directory 1631called @file{@var{cpu}.h}. This file should define any target specific 1632information which may be needed outside of the BFD code. In particular 1633it should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER}, 1634@samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS} 1635macros to create a table mapping the number used to identify a 1636relocation to a name describing that relocation. 1637 1638While not a BFD component, you probably also want to make the binutils 1639program @samp{readelf} parse your ELF objects. For this, you need to add 1640code for @code{EM_@var{cpu}} as appropriate in @file{binutils/readelf.c}. 1641 1642@node BFD ELF processor linker 1643@subsubsection Processor specific linker support 1644 1645The linker will be much more efficient if you define a relocate section 1646function. This will permit BFD to use the ELF specific linker support. 1647 1648If you do not define a relocate section function, BFD must use the 1649generic linker support, which requires converting all symbols and 1650relocations into BFD @samp{asymbol} and @samp{arelent} structures. In 1651this case, relocations will be handled by calling 1652@samp{bfd_perform_relocation}, which will use the howto structures you 1653have defined. @xref{BFD relocation handling}. 1654 1655In order to support linking into a different object file format, such as 1656S-records, @samp{bfd_perform_relocation} must work correctly with your 1657howto structures, so you can't skip that step. However, if you define 1658the relocate section function, then in the normal case of linking into 1659an ELF file the linker will not need to convert symbols and relocations, 1660and will be much more efficient. 1661 1662To use a relocation section function, define the macro 1663@samp{elf_backend_relocate_section} as the name of a function which will 1664take the contents of a section, as well as relocation, symbol, and other 1665information, and modify the section contents according to the relocation 1666information. In simple cases, this is little more than a loop over the 1667relocations which computes the value of each relocation and calls 1668@samp{_bfd_final_link_relocate}. The function must check for a 1669relocatable link, and in that case normally needs to do nothing other 1670than adjust the addend for relocations against a section symbol. 1671 1672The complex cases generally have to do with dynamic linker support. GOT 1673and PLT relocations must be handled specially, and the linker normally 1674arranges to set up the GOT and PLT sections while handling relocations. 1675When generating a shared library, random relocations must normally be 1676copied into the shared library, or converted to RELATIVE relocations 1677when possible. 1678 1679@node BFD ELF processor other 1680@subsubsection Other processor specific support options 1681 1682There are many other macros which may be defined in 1683@file{elf@var{nn}-@var{cpu}.c}. These macros may be found in 1684@file{elfxx-target.h}. 1685 1686Macros may be used to override some of the generic ELF target vector 1687functions. 1688 1689Several processor specific hook functions which may be defined as 1690macros. These functions are found as function pointers in the 1691@samp{elf_backend_data} structure defined in @file{elf-bfd.h}. In 1692general, a hook function is set by defining a macro 1693@samp{elf_backend_@var{name}}. 1694 1695There are a few processor specific constants which may also be defined. 1696These are again found in the @samp{elf_backend_data} structure. 1697 1698I will not define the various functions and constants here; see the 1699comments in @file{elf-bfd.h}. 1700 1701Normally any odd characteristic of a particular ELF processor is handled 1702via a hook function. For example, the special @samp{SHN_MIPS_SCOMMON} 1703section number found in MIPS ELF is handled via the hooks 1704@samp{section_from_bfd_section}, @samp{symbol_processing}, 1705@samp{add_symbol_hook}, and @samp{output_symbol_hook}. 1706 1707Dynamic linking support, which involves processor specific relocations 1708requiring special handling, is also implemented via hook functions. 1709 1710@node BFD ELF core files 1711@subsection BFD ELF core files 1712@cindex elf core files 1713 1714On native ELF Unix systems, core files are generated without any 1715sections. Instead, they only have program segments. 1716 1717When BFD is used to read an ELF core file, the BFD sections will 1718actually represent program segments. Since ELF program segments do not 1719have names, BFD will invent names like @samp{segment@var{n}} where 1720@var{n} is a number. 1721 1722A single ELF program segment may include both an initialized part and an 1723uninitialized part. The size of the initialized part is given by the 1724@samp{p_filesz} field. The total size of the segment is given by the 1725@samp{p_memsz} field. If @samp{p_memsz} is larger than @samp{p_filesz}, 1726then the extra space is uninitialized, or, more precisely, initialized 1727to zero. 1728 1729BFD will represent such a program segment as two different sections. 1730The first, named @samp{segment@var{n}a}, will represent the initialized 1731part of the program segment. The second, named @samp{segment@var{n}b}, 1732will represent the uninitialized part. 1733 1734ELF core files store special information such as register values in 1735program segments with the type @samp{PT_NOTE}. BFD will attempt to 1736interpret the information in these segments, and will create additional 1737sections holding the information. Some of this interpretation requires 1738information found in the host header file @file{sys/procfs.h}, and so 1739will only work when BFD is built on a native system. 1740 1741BFD does not currently provide any way to create an ELF core file. In 1742general, BFD does not provide a way to create core files. The way to 1743implement this would be to write @samp{bfd_set_format} and 1744@samp{bfd_write_contents} routines for the @samp{bfd_core} type; see 1745@ref{BFD target vector format}. 1746 1747@node BFD ELF future 1748@subsection BFD ELF future 1749 1750The current dynamic linking support has too much code duplication. 1751While each processor has particular differences, much of the dynamic 1752linking support is quite similar for each processor. The GOT and PLT 1753are handled in fairly similar ways, the details of -Bsymbolic linking 1754are generally similar, etc. This code should be reworked to use more 1755generic functions, eliminating the duplication. 1756 1757Similarly, the relocation handling has too much duplication. Many of 1758the @samp{reloc_type_lookup} and @samp{info_to_howto} functions are 1759quite similar. The relocate section functions are also often quite 1760similar, both in the standard linker handling and the dynamic linker 1761handling. Many of the COFF processor specific backends share a single 1762relocate section function (@samp{_bfd_coff_generic_relocate_section}), 1763and it should be possible to do something like this for the ELF targets 1764as well. 1765 1766The appearance of the processor specific magic number in 1767@samp{prep_headers} in @file{elf.c} is somewhat bogus. It should be 1768possible to add support for a new processor without changing the generic 1769support. 1770 1771The processor function hooks and constants are ad hoc and need better 1772documentation. 1773 1774@node BFD glossary 1775@section BFD glossary 1776@cindex glossary for bfd 1777@cindex bfd glossary 1778 1779This is a short glossary of some BFD terms. 1780 1781@table @asis 1782@item a.out 1783The a.out object file format. The original Unix object file format. 1784Still used on SunOS, though not Solaris. Supports only three sections. 1785 1786@item archive 1787A collection of object files produced and manipulated by the @samp{ar} 1788program. 1789 1790@item backend 1791The implementation within BFD of a particular object file format. The 1792set of functions which appear in a particular target vector. 1793 1794@item BFD 1795The BFD library itself. Also, each object file, archive, or executable 1796opened by the BFD library has the type @samp{bfd *}, and is sometimes 1797referred to as a bfd. 1798 1799@item COFF 1800The Common Object File Format. Used on Unix SVR3. Used by some 1801embedded targets, although ELF is normally better. 1802 1803@item DLL 1804A shared library on Windows. 1805 1806@item dynamic linker 1807When a program linked against a shared library is run, the dynamic 1808linker will locate the appropriate shared library and arrange to somehow 1809include it in the running image. 1810 1811@item dynamic object 1812Another name for an ELF shared library. 1813 1814@item ECOFF 1815The Extended Common Object File Format. Used on Alpha Digital Unix 1816(formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF. 1817 1818@item ELF 1819The Executable and Linking Format. The object file format used on most 1820modern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also 1821used on many embedded systems. 1822 1823@item executable 1824A program, with instructions and symbols, and perhaps dynamic linking 1825information. Normally produced by a linker. 1826 1827@item LMA 1828Load Memory Address. This is the address at which a section will be 1829loaded. Compare with VMA, below. 1830 1831@item NLM 1832NetWare Loadable Module. Used to describe the format of an object which 1833be loaded into NetWare, which is some kind of PC based network server 1834program. 1835 1836@item object file 1837A binary file including machine instructions, symbols, and relocation 1838information. Normally produced by an assembler. 1839 1840@item object file format 1841The format of an object file. Typically object files and executables 1842for a particular system are in the same format, although executables 1843will not contain any relocation information. 1844 1845@item PE 1846The Portable Executable format. This is the object file format used for 1847Windows (specifically, Win32) object files. It is based closely on 1848COFF, but has a few significant differences. 1849 1850@item PEI 1851The Portable Executable Image format. This is the object file format 1852used for Windows (specifically, Win32) executables. It is very similar 1853to PE, but includes some additional header information. 1854 1855@item relocations 1856Information used by the linker to adjust section contents. Also called 1857relocs. 1858 1859@item section 1860Object files and executable are composed of sections. Sections have 1861optional data and optional relocation information. 1862 1863@item shared library 1864A library of functions which may be used by many executables without 1865actually being linked into each executable. There are several different 1866implementations of shared libraries, each having slightly different 1867features. 1868 1869@item symbol 1870Each object file and executable may have a list of symbols, often 1871referred to as the symbol table. A symbol is basically a name and an 1872address. There may also be some additional information like the type of 1873symbol, although the type of a symbol is normally something simple like 1874function or object, and should be confused with the more complex C 1875notion of type. Typically every global function and variable in a C 1876program will have an associated symbol. 1877 1878@item target vector 1879A set of functions which implement support for a particular object file 1880format. The @samp{bfd_target} structure. 1881 1882@item Win32 1883The current Windows API, implemented by Windows 95 and later and Windows 1884NT 3.51 and later, but not by Windows 3.1. 1885 1886@item XCOFF 1887The eXtended Common Object File Format. Used on AIX. A variant of 1888COFF, with a completely different symbol table implementation. 1889 1890@item VMA 1891Virtual Memory Address. This is the address a section will have when 1892an executable is run. Compare with LMA, above. 1893@end table 1894 1895@node Index 1896@unnumberedsec Index 1897@printindex cp 1898 1899@contents 1900@bye 1901