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