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