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