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