| This is bfd.info, produced by makeinfo version 4.0 from bfd.texinfo. |
| |
| START-INFO-DIR-ENTRY |
| * Bfd: (bfd). The Binary File Descriptor library. |
| END-INFO-DIR-ENTRY |
| |
| This file documents the BFD library. |
| |
| Copyright (C) 1991, 2000 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.1 |
| or any later version published by the Free Software Foundation; |
| with no Invariant Sections, with no Front-Cover Texts, and with no |
| Back-Cover Texts. A copy of the license is included in the |
| section entitled "GNU Free Documentation License". |
| |
| |
| File: bfd.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) |
| |
| This file documents the binary file descriptor library libbfd. |
| |
| * Menu: |
| |
| * Overview:: Overview of BFD |
| * BFD front end:: BFD front end |
| * BFD back ends:: BFD back ends |
| * GNU Free Documentation License:: GNU Free Documentation License |
| * Index:: Index |
| |
| |
| File: bfd.info, Node: Overview, Next: BFD front end, Prev: Top, Up: Top |
| |
| Introduction |
| ************ |
| |
| BFD is a package which allows applications to use the same routines |
| to operate on object files whatever the object file format. A new |
| object file format can be supported simply by creating a new BFD back |
| end and adding it to the library. |
| |
| BFD is split into two parts: the front end, and the back ends (one |
| for each object file format). |
| * The front end of BFD provides the interface to the user. It manages |
| memory and various canonical data structures. The front end also |
| decides which back end to use and when to call back end routines. |
| |
| * The back ends provide BFD its view of the real world. Each back |
| end provides a set of calls which the BFD front end can use to |
| maintain its canonical form. The back ends also may keep around |
| information for their own use, for greater efficiency. |
| |
| * Menu: |
| |
| * History:: History |
| * How It Works:: How It Works |
| * What BFD Version 2 Can Do:: What BFD Version 2 Can Do |
| |
| |
| File: bfd.info, Node: History, Next: How It Works, Prev: Overview, Up: Overview |
| |
| History |
| ======= |
| |
| One spur behind BFD was the desire, on the part of the GNU 960 team |
| at Intel Oregon, for interoperability of applications on their COFF and |
| b.out file formats. Cygnus was providing GNU support for the team, and |
| was contracted to provide the required functionality. |
| |
| The name came from a conversation David Wallace was having with |
| Richard Stallman about the library: RMS said that it would be quite |
| hard--David said "BFD". Stallman was right, but the name stuck. |
| |
| At the same time, Ready Systems wanted much the same thing, but for |
| different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k |
| coff. |
| |
| BFD was first implemented by members of Cygnus Support; Steve |
| Chamberlain (`sac@cygnus.com'), John Gilmore (`gnu@cygnus.com'), K. |
| Richard Pixley (`rich@cygnus.com') and David Henkel-Wallace |
| (`gumby@cygnus.com'). |
| |
| |
| File: bfd.info, Node: How It Works, Next: What BFD Version 2 Can Do, Prev: History, Up: Overview |
| |
| How To Use BFD |
| ============== |
| |
| To use the library, include `bfd.h' and link with `libbfd.a'. |
| |
| BFD provides a common interface to the parts of an object file for a |
| calling application. |
| |
| When an application sucessfully opens a target file (object, |
| archive, or whatever), a pointer to an internal structure is returned. |
| This pointer points to a structure called `bfd', described in `bfd.h'. |
| Our convention is to call this pointer a BFD, and instances of it |
| within code `abfd'. All operations on the target object file are |
| applied as methods to the BFD. The mapping is defined within `bfd.h' |
| in a set of macros, all beginning with `bfd_' to reduce namespace |
| pollution. |
| |
| For example, this sequence does what you would probably expect: |
| return the number of sections in an object file attached to a BFD |
| `abfd'. |
| |
| #include "bfd.h" |
| |
| unsigned int number_of_sections(abfd) |
| bfd *abfd; |
| { |
| return bfd_count_sections(abfd); |
| } |
| |
| The abstraction used within BFD is that an object file has: |
| |
| * a header, |
| |
| * a number of sections containing raw data (*note Sections::), |
| |
| * a set of relocations (*note Relocations::), and |
| |
| * some symbol information (*note Symbols::). |
| |
| Also, BFDs opened for archives have the additional attribute of an index |
| and contain subordinate BFDs. This approach is fine for a.out and coff, |
| but loses efficiency when applied to formats such as S-records and |
| IEEE-695. |
| |
| |
| File: bfd.info, Node: What BFD Version 2 Can Do, Prev: How It Works, Up: Overview |
| |
| What BFD Version 2 Can Do |
| ========================= |
| |
| When an object file is opened, BFD subroutines automatically |
| determine the format of the input object file. They then build a |
| descriptor in memory with pointers to routines that will be used to |
| access elements of the object file's data structures. |
| |
| As different information from the the object files is required, BFD |
| reads from different sections of the file and processes them. For |
| example, a very common operation for the linker is processing symbol |
| tables. Each BFD back end provides a routine for converting between |
| the object file's representation of symbols and an internal canonical |
| format. When the linker asks for the symbol table of an object file, it |
| calls through a memory pointer to the routine from the relevant BFD |
| back end which reads and converts the table into a canonical form. The |
| linker then operates upon the canonical form. When the link is finished |
| and the linker writes the output file's symbol table, another BFD back |
| end routine is called to take the newly created symbol table and |
| convert it into the chosen output format. |
| |
| * Menu: |
| |
| * BFD information loss:: Information Loss |
| * Canonical format:: The BFD canonical object-file format |
| |
| |
| File: bfd.info, Node: BFD information loss, Next: Canonical format, Up: What BFD Version 2 Can Do |
| |
| Information Loss |
| ---------------- |
| |
| _Information can be lost during output._ The output formats |
| supported by BFD do not provide identical facilities, and information |
| which can be described in one form has nowhere to go in another format. |
| One example of this is alignment information in `b.out'. There is |
| nowhere in an `a.out' format file to store alignment information on the |
| contained data, so when a file is linked from `b.out' and an `a.out' |
| image is produced, alignment information will not propagate to the |
| output file. (The linker will still use the alignment information |
| internally, so the link is performed correctly). |
| |
| Another example is COFF section names. COFF files may contain an |
| unlimited number of sections, each one with a textual section name. If |
| the target of the link is a format which does not have many sections |
| (e.g., `a.out') or has sections without names (e.g., the Oasys format), |
| the link cannot be done simply. You can circumvent this problem by |
| describing the desired input-to-output section mapping with the linker |
| command language. |
| |
| _Information can be lost during canonicalization._ The BFD internal |
| canonical form of the external formats is not exhaustive; there are |
| structures in input formats for which there is no direct representation |
| internally. This means that the BFD back ends cannot maintain all |
| possible data richness through the transformation between external to |
| internal and back to external formats. |
| |
| This limitation is only a problem when an application reads one |
| format and writes another. Each BFD back end is responsible for |
| maintaining as much data as possible, and the internal BFD canonical |
| form has structures which are opaque to the BFD core, and exported only |
| to the back ends. When a file is read in one format, the canonical form |
| is generated for BFD and the application. At the same time, the back |
| end saves away any information which may otherwise be lost. If the data |
| is then written back in the same format, the back end routine will be |
| able to use the canonical form provided by the BFD core as well as the |
| information it prepared earlier. Since there is a great deal of |
| commonality between back ends, there is no information lost when |
| linking or copying big endian COFF to little endian COFF, or `a.out' to |
| `b.out'. When a mixture of formats is linked, the information is only |
| lost from the files whose format differs from the destination. |
| |
| |
| File: bfd.info, Node: Canonical format, Prev: BFD information loss, Up: What BFD Version 2 Can Do |
| |
| The BFD canonical object-file format |
| ------------------------------------ |
| |
| The greatest potential for loss of information occurs when there is |
| the least overlap between the information provided by the source |
| format, that stored by the canonical format, and that needed by the |
| destination format. A brief description of the canonical form may help |
| you understand which kinds of data you can count on preserving across |
| conversions. |
| |
| _files_ |
| Information stored on a per-file basis includes target machine |
| architecture, particular implementation format type, a demand |
| pageable bit, and a write protected bit. Information like Unix |
| magic numbers is not stored here--only the magic numbers' meaning, |
| so a `ZMAGIC' file would have both the demand pageable bit and the |
| write protected text bit set. The byte order of the target is |
| stored on a per-file basis, so that big- and little-endian object |
| files may be used with one another. |
| |
| _sections_ |
| Each section in the input file contains the name of the section, |
| the section's original address in the object file, size and |
| alignment information, various flags, and pointers into other BFD |
| data structures. |
| |
| _symbols_ |
| Each symbol contains a pointer to the information for the object |
| file which originally defined it, its name, its value, and various |
| flag bits. When a BFD back end reads in a symbol table, it |
| relocates all symbols to make them relative to the base of the |
| section where they were defined. Doing this ensures that each |
| symbol points to its containing section. Each symbol also has a |
| varying amount of hidden private data for the BFD back end. Since |
| the symbol points to the original file, the private data format |
| for that symbol is accessible. `ld' can operate on a collection |
| of symbols of wildly different formats without problems. |
| |
| Normal global and simple local symbols are maintained on output, |
| so an output file (no matter its format) will retain symbols |
| pointing to functions and to global, static, and common variables. |
| Some symbol information is not worth retaining; in `a.out', type |
| information is stored in the symbol table as long symbol names. |
| This information would be useless to most COFF debuggers; the |
| linker has command line switches to allow users to throw it away. |
| |
| There is one word of type information within the symbol, so if the |
| format supports symbol type information within symbols (for |
| example, COFF, IEEE, Oasys) and the type is simple enough to fit |
| within one word (nearly everything but aggregates), the |
| information will be preserved. |
| |
| _relocation level_ |
| Each canonical BFD relocation record contains a pointer to the |
| symbol to relocate to, the offset of the data to relocate, the |
| section the data is in, and a pointer to a relocation type |
| descriptor. Relocation is performed by passing messages through |
| the relocation type descriptor and the symbol pointer. Therefore, |
| relocations can be performed on output data using a relocation |
| method that is only available in one of the input formats. For |
| instance, Oasys provides a byte relocation format. A relocation |
| record requesting this relocation type would point indirectly to a |
| routine to perform this, so the relocation may be performed on a |
| byte being written to a 68k COFF file, even though 68k COFF has no |
| such relocation type. |
| |
| _line numbers_ |
| Object formats can contain, for debugging purposes, some form of |
| mapping between symbols, source line numbers, and addresses in the |
| output file. These addresses have to be relocated along with the |
| symbol information. Each symbol with an associated list of line |
| number records points to the first record of the list. The head |
| of a line number list consists of a pointer to the symbol, which |
| allows finding out the address of the function whose line number |
| is being described. The rest of the list is made up of pairs: |
| offsets into the section and line numbers. Any format which can |
| simply derive this information can pass it successfully between |
| formats (COFF, IEEE and Oasys). |
| |
| |
| File: bfd.info, Node: BFD front end, Next: BFD back ends, Prev: Overview, Up: Top |
| |
| BFD front end |
| ************* |
| |
| `typedef bfd' |
| ============= |
| |
| A BFD has type `bfd'; objects of this type are the cornerstone of |
| any application using BFD. Using BFD consists of making references |
| though the BFD and to data in the BFD. |
| |
| Here is the structure that defines the type `bfd'. It contains the |
| major data about the file and pointers to the rest of the data. |
| |
| |
| struct _bfd |
| { |
| /* The filename the application opened the BFD with. */ |
| CONST char *filename; |
| |
| /* A pointer to the target jump table. */ |
| const struct bfd_target *xvec; |
| |
| /* To avoid dragging too many header files into every file that |
| includes ``bfd.h'', IOSTREAM has been declared as a "char |
| *", and MTIME as a "long". Their correct types, to which they |
| are cast when used, are "FILE *" and "time_t". The iostream |
| is the result of an fopen on the filename. However, if the |
| BFD_IN_MEMORY flag is set, then iostream is actually a pointer |
| to a bfd_in_memory struct. */ |
| PTR iostream; |
| |
| /* Is the file descriptor being cached? That is, can it be closed as |
| needed, and re-opened when accessed later? */ |
| |
| boolean cacheable; |
| |
| /* Marks whether there was a default target specified when the |
| BFD was opened. This is used to select which matching algorithm |
| to use to choose the back end. */ |
| |
| boolean target_defaulted; |
| |
| /* The caching routines use these to maintain a |
| least-recently-used list of BFDs */ |
| |
| struct _bfd *lru_prev, *lru_next; |
| |
| /* When a file is closed by the caching routines, BFD retains |
| state information on the file here: */ |
| |
| file_ptr where; |
| |
| /* and here: (``once'' means at least once) */ |
| |
| boolean opened_once; |
| |
| /* Set if we have a locally maintained mtime value, rather than |
| getting it from the file each time: */ |
| |
| boolean mtime_set; |
| |
| /* File modified time, if mtime_set is true: */ |
| |
| long mtime; |
| |
| /* Reserved for an unimplemented file locking extension.*/ |
| |
| int ifd; |
| |
| /* The format which belongs to the BFD. (object, core, etc.) */ |
| |
| bfd_format format; |
| |
| /* The direction the BFD was opened with*/ |
| |
| enum bfd_direction {no_direction = 0, |
| read_direction = 1, |
| write_direction = 2, |
| both_direction = 3} direction; |
| |
| /* Format_specific flags*/ |
| |
| flagword flags; |
| |
| /* Currently my_archive is tested before adding origin to |
| anything. I believe that this can become always an add of |
| origin, with origin set to 0 for non archive files. */ |
| |
| file_ptr origin; |
| |
| /* Remember when output has begun, to stop strange things |
| from happening. */ |
| boolean output_has_begun; |
| |
| /* Pointer to linked list of sections*/ |
| struct sec *sections; |
| |
| /* The number of sections */ |
| unsigned int section_count; |
| |
| /* Stuff only useful for object files: |
| The start address. */ |
| bfd_vma start_address; |
| |
| /* Used for input and output*/ |
| unsigned int symcount; |
| |
| /* Symbol table for output BFD (with symcount entries) */ |
| struct symbol_cache_entry **outsymbols; |
| |
| /* Pointer to structure which contains architecture information*/ |
| const struct bfd_arch_info *arch_info; |
| |
| /* Stuff only useful for archives:*/ |
| PTR arelt_data; |
| struct _bfd *my_archive; /* The containing archive BFD. */ |
| struct _bfd *next; /* The next BFD in the archive. */ |
| struct _bfd *archive_head; /* The first BFD in the archive. */ |
| boolean has_armap; |
| |
| /* A chain of BFD structures involved in a link. */ |
| struct _bfd *link_next; |
| |
| /* A field used by _bfd_generic_link_add_archive_symbols. This will |
| be used only for archive elements. */ |
| int archive_pass; |
| |
| /* Used by the back end to hold private data. */ |
| |
| union |
| { |
| struct aout_data_struct *aout_data; |
| struct artdata *aout_ar_data; |
| struct _oasys_data *oasys_obj_data; |
| struct _oasys_ar_data *oasys_ar_data; |
| struct coff_tdata *coff_obj_data; |
| struct pe_tdata *pe_obj_data; |
| struct xcoff_tdata *xcoff_obj_data; |
| struct ecoff_tdata *ecoff_obj_data; |
| struct ieee_data_struct *ieee_data; |
| struct ieee_ar_data_struct *ieee_ar_data; |
| struct srec_data_struct *srec_data; |
| struct ihex_data_struct *ihex_data; |
| struct tekhex_data_struct *tekhex_data; |
| struct elf_obj_tdata *elf_obj_data; |
| struct nlm_obj_tdata *nlm_obj_data; |
| struct bout_data_struct *bout_data; |
| struct sun_core_struct *sun_core_data; |
| struct sco5_core_struct *sco5_core_data; |
| struct trad_core_struct *trad_core_data; |
| struct som_data_struct *som_data; |
| struct hpux_core_struct *hpux_core_data; |
| struct hppabsd_core_struct *hppabsd_core_data; |
| struct sgi_core_struct *sgi_core_data; |
| struct lynx_core_struct *lynx_core_data; |
| struct osf_core_struct *osf_core_data; |
| struct cisco_core_struct *cisco_core_data; |
| struct versados_data_struct *versados_data; |
| struct netbsd_core_struct *netbsd_core_data; |
| PTR any; |
| } tdata; |
| |
| /* Used by the application to hold private data*/ |
| PTR usrdata; |
| |
| /* Where all the allocated stuff under this BFD goes. This is a |
| struct objalloc *, but we use PTR to avoid requiring the inclusion of |
| objalloc.h. */ |
| PTR memory; |
| }; |
| |
| Error reporting |
| =============== |
| |
| Most BFD functions return nonzero on success (check their individual |
| documentation for precise semantics). On an error, they call |
| `bfd_set_error' to set an error condition that callers can check by |
| calling `bfd_get_error'. If that returns `bfd_error_system_call', then |
| check `errno'. |
| |
| The easiest way to report a BFD error to the user is to use |
| `bfd_perror'. |
| |
| Type `bfd_error_type' |
| --------------------- |
| |
| The values returned by `bfd_get_error' are defined by the enumerated |
| type `bfd_error_type'. |
| |
| |
| typedef enum bfd_error |
| { |
| bfd_error_no_error = 0, |
| bfd_error_system_call, |
| bfd_error_invalid_target, |
| bfd_error_wrong_format, |
| bfd_error_invalid_operation, |
| bfd_error_no_memory, |
| bfd_error_no_symbols, |
| bfd_error_no_armap, |
| bfd_error_no_more_archived_files, |
| bfd_error_malformed_archive, |
| bfd_error_file_not_recognized, |
| bfd_error_file_ambiguously_recognized, |
| bfd_error_no_contents, |
| bfd_error_nonrepresentable_section, |
| bfd_error_no_debug_section, |
| bfd_error_bad_value, |
| bfd_error_file_truncated, |
| bfd_error_file_too_big, |
| bfd_error_invalid_error_code |
| } bfd_error_type; |
| |
| `bfd_get_error' |
| ............... |
| |
| *Synopsis* |
| bfd_error_type bfd_get_error (void); |
| *Description* |
| Return the current BFD error condition. |
| |
| `bfd_set_error' |
| ............... |
| |
| *Synopsis* |
| void bfd_set_error (bfd_error_type error_tag); |
| *Description* |
| Set the BFD error condition to be ERROR_TAG. |
| |
| `bfd_errmsg' |
| ............ |
| |
| *Synopsis* |
| CONST char *bfd_errmsg (bfd_error_type error_tag); |
| *Description* |
| Return a string describing the error ERROR_TAG, or the system error if |
| ERROR_TAG is `bfd_error_system_call'. |
| |
| `bfd_perror' |
| ............ |
| |
| *Synopsis* |
| void bfd_perror (CONST char *message); |
| *Description* |
| Print to the standard error stream a string describing the last BFD |
| error that occurred, or the last system error if the last BFD error was |
| a system call failure. If MESSAGE is non-NULL and non-empty, the error |
| string printed is preceded by MESSAGE, a colon, and a space. It is |
| followed by a newline. |
| |
| BFD error handler |
| ----------------- |
| |
| Some BFD functions want to print messages describing the problem. |
| They call a BFD error handler function. This function may be overriden |
| by the program. |
| |
| The BFD error handler acts like printf. |
| |
| |
| typedef void (*bfd_error_handler_type) PARAMS ((const char *, ...)); |
| |
| `bfd_set_error_handler' |
| ....................... |
| |
| *Synopsis* |
| bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type); |
| *Description* |
| Set the BFD error handler function. Returns the previous function. |
| |
| `bfd_set_error_program_name' |
| ............................ |
| |
| *Synopsis* |
| void bfd_set_error_program_name (const char *); |
| *Description* |
| Set the program name to use when printing a BFD error. This is printed |
| before the error message followed by a colon and space. The string |
| must not be changed after it is passed to this function. |
| |
| `bfd_get_error_handler' |
| ....................... |
| |
| *Synopsis* |
| bfd_error_handler_type bfd_get_error_handler (void); |
| *Description* |
| Return the BFD error handler function. |
| |
| Symbols |
| ======= |
| |
| `bfd_get_reloc_upper_bound' |
| ........................... |
| |
| *Synopsis* |
| long bfd_get_reloc_upper_bound(bfd *abfd, asection *sect); |
| *Description* |
| Return the number of bytes required to store the relocation information |
| associated with section SECT attached to bfd ABFD. If an error occurs, |
| return -1. |
| |
| `bfd_canonicalize_reloc' |
| ........................ |
| |
| *Synopsis* |
| long bfd_canonicalize_reloc |
| (bfd *abfd, |
| asection *sec, |
| arelent **loc, |
| asymbol **syms); |
| *Description* |
| Call the back end associated with the open BFD ABFD and translate the |
| external form of the relocation information attached to SEC into the |
| internal canonical form. Place the table into memory at LOC, which has |
| been preallocated, usually by a call to `bfd_get_reloc_upper_bound'. |
| Returns the number of relocs, or -1 on error. |
| |
| The SYMS table is also needed for horrible internal magic reasons. |
| |
| `bfd_set_reloc' |
| ............... |
| |
| *Synopsis* |
| void bfd_set_reloc |
| (bfd *abfd, asection *sec, arelent **rel, unsigned int count) |
| *Description* |
| Set the relocation pointer and count within section SEC to the values |
| REL and COUNT. The argument ABFD is ignored. |
| |
| `bfd_set_file_flags' |
| .................... |
| |
| *Synopsis* |
| boolean bfd_set_file_flags(bfd *abfd, flagword flags); |
| *Description* |
| Set the flag word in the BFD ABFD to the value FLAGS. |
| |
| Possible errors are: |
| * `bfd_error_wrong_format' - The target bfd was not of object format. |
| |
| * `bfd_error_invalid_operation' - The target bfd was open for |
| reading. |
| |
| * `bfd_error_invalid_operation' - The flag word contained a bit |
| which was not applicable to the type of file. E.g., an attempt |
| was made to set the `D_PAGED' bit on a BFD format which does not |
| support demand paging. |
| |
| `bfd_get_arch_size' |
| ................... |
| |
| *Synopsis* |
| int bfd_get_arch_size (bfd *abfd); |
| *Description* |
| Returns the architecture address size, in bits, as determined by the |
| object file's format. For ELF, this information is included in the |
| header. |
| |
| *Returns* |
| Returns the arch size in bits if known, `-1' otherwise. |
| |
| `bfd_get_sign_extend_vma' |
| ......................... |
| |
| *Synopsis* |
| int bfd_get_sign_extend_vma (bfd *abfd); |
| *Description* |
| Indicates if the target architecture "naturally" sign extends an |
| address. Some architectures implicitly sign extend address values when |
| they are converted to types larger than the size of an address. For |
| instance, bfd_get_start_address() will return an address sign extended |
| to fill a bfd_vma when this is the case. |
| |
| *Returns* |
| Returns `1' if the target architecture is known to sign extend |
| addresses, `0' if the target architecture is known to not sign extend |
| addresses, and `-1' otherwise. |
| |
| `bfd_set_start_address' |
| ....................... |
| |
| *Synopsis* |
| boolean bfd_set_start_address(bfd *abfd, bfd_vma vma); |
| *Description* |
| Make VMA the entry point of output BFD ABFD. |
| |
| *Returns* |
| Returns `true' on success, `false' otherwise. |
| |
| `bfd_get_mtime' |
| ............... |
| |
| *Synopsis* |
| long bfd_get_mtime(bfd *abfd); |
| *Description* |
| Return the file modification time (as read from the file system, or |
| from the archive header for archive members). |
| |
| `bfd_get_size' |
| .............. |
| |
| *Synopsis* |
| long bfd_get_size(bfd *abfd); |
| *Description* |
| Return the file size (as read from file system) for the file associated |
| with BFD ABFD. |
| |
| The initial motivation for, and use of, this routine is not so we |
| can get the exact size of the object the BFD applies to, since that |
| might not be generally possible (archive members for example). It |
| would be ideal if someone could eventually modify it so that such |
| results were guaranteed. |
| |
| Instead, we want to ask questions like "is this NNN byte sized |
| object I'm about to try read from file offset YYY reasonable?" As as |
| example of where we might do this, some object formats use string |
| tables for which the first `sizeof (long)' bytes of the table contain |
| the size of the table itself, including the size bytes. If an |
| application tries to read what it thinks is one of these string tables, |
| without some way to validate the size, and for some reason the size is |
| wrong (byte swapping error, wrong location for the string table, etc.), |
| the only clue is likely to be a read error when it tries to read the |
| table, or a "virtual memory exhausted" error when it tries to allocate |
| 15 bazillon bytes of space for the 15 bazillon byte table it is about |
| to read. This function at least allows us to answer the quesion, "is |
| the size reasonable?". |
| |
| `bfd_get_gp_size' |
| ................. |
| |
| *Synopsis* |
| int bfd_get_gp_size(bfd *abfd); |
| *Description* |
| Return the maximum size of objects to be optimized using the GP |
| register under MIPS ECOFF. This is typically set by the `-G' argument |
| to the compiler, assembler or linker. |
| |
| `bfd_set_gp_size' |
| ................. |
| |
| *Synopsis* |
| void bfd_set_gp_size(bfd *abfd, int i); |
| *Description* |
| Set the maximum size of objects to be optimized using the GP register |
| under ECOFF or MIPS ELF. This is typically set by the `-G' argument to |
| the compiler, assembler or linker. |
| |
| `bfd_scan_vma' |
| .............. |
| |
| *Synopsis* |
| bfd_vma bfd_scan_vma(CONST char *string, CONST char **end, int base); |
| *Description* |
| Convert, like `strtoul', a numerical expression STRING into a `bfd_vma' |
| integer, and return that integer. (Though without as many bells and |
| whistles as `strtoul'.) The expression is assumed to be unsigned |
| (i.e., positive). If given a BASE, it is used as the base for |
| conversion. A base of 0 causes the function to interpret the string in |
| hex if a leading "0x" or "0X" is found, otherwise in octal if a leading |
| zero is found, otherwise in decimal. |
| |
| Overflow is not detected. |
| |
| `bfd_copy_private_bfd_data' |
| ........................... |
| |
| *Synopsis* |
| boolean bfd_copy_private_bfd_data(bfd *ibfd, bfd *obfd); |
| *Description* |
| Copy private BFD information from the BFD IBFD to the the BFD OBFD. |
| Return `true' on success, `false' on error. Possible error returns are: |
| |
| * `bfd_error_no_memory' - Not enough memory exists to create private |
| data for OBFD. |
| |
| #define bfd_copy_private_bfd_data(ibfd, obfd) \ |
| BFD_SEND (obfd, _bfd_copy_private_bfd_data, \ |
| (ibfd, obfd)) |
| |
| `bfd_merge_private_bfd_data' |
| ............................ |
| |
| *Synopsis* |
| boolean bfd_merge_private_bfd_data(bfd *ibfd, bfd *obfd); |
| *Description* |
| Merge private BFD information from the BFD IBFD to the the output file |
| BFD OBFD when linking. Return `true' on success, `false' on error. |
| Possible error returns are: |
| |
| * `bfd_error_no_memory' - Not enough memory exists to create private |
| data for OBFD. |
| |
| #define bfd_merge_private_bfd_data(ibfd, obfd) \ |
| BFD_SEND (obfd, _bfd_merge_private_bfd_data, \ |
| (ibfd, obfd)) |
| |
| `bfd_set_private_flags' |
| ....................... |
| |
| *Synopsis* |
| boolean bfd_set_private_flags(bfd *abfd, flagword flags); |
| *Description* |
| Set private BFD flag information in the BFD ABFD. Return `true' on |
| success, `false' on error. Possible error returns are: |
| |
| * `bfd_error_no_memory' - Not enough memory exists to create private |
| data for OBFD. |
| |
| #define bfd_set_private_flags(abfd, flags) \ |
| BFD_SEND (abfd, _bfd_set_private_flags, \ |
| (abfd, flags)) |
| |
| `stuff' |
| ....... |
| |
| *Description* |
| Stuff which should be documented: |
| #define bfd_sizeof_headers(abfd, reloc) \ |
| BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc)) |
| |
| #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \ |
| BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, sec, syms, off, file, func, line)) |
| |
| /* Do these three do anything useful at all, for any back end? */ |
| #define bfd_debug_info_start(abfd) \ |
| BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) |
| |
| #define bfd_debug_info_end(abfd) \ |
| BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) |
| |
| #define bfd_debug_info_accumulate(abfd, section) \ |
| BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) |
| |
| |
| #define bfd_stat_arch_elt(abfd, stat) \ |
| BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat)) |
| |
| #define bfd_update_armap_timestamp(abfd) \ |
| BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd)) |
| |
| #define bfd_set_arch_mach(abfd, arch, mach)\ |
| BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) |
| |
| #define bfd_relax_section(abfd, section, link_info, again) \ |
| BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again)) |
| |
| #define bfd_gc_sections(abfd, link_info) \ |
| BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info)) |
| |
| #define bfd_link_hash_table_create(abfd) \ |
| BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd)) |
| |
| #define bfd_link_add_symbols(abfd, info) \ |
| BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info)) |
| |
| #define bfd_final_link(abfd, info) \ |
| BFD_SEND (abfd, _bfd_final_link, (abfd, info)) |
| |
| #define bfd_free_cached_info(abfd) \ |
| BFD_SEND (abfd, _bfd_free_cached_info, (abfd)) |
| |
| #define bfd_get_dynamic_symtab_upper_bound(abfd) \ |
| BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd)) |
| |
| #define bfd_print_private_bfd_data(abfd, file)\ |
| BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file)) |
| |
| #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \ |
| BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols)) |
| |
| #define bfd_get_dynamic_reloc_upper_bound(abfd) \ |
| BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd)) |
| |
| #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \ |
| BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms)) |
| |
| extern bfd_byte *bfd_get_relocated_section_contents |
| PARAMS ((bfd *, struct bfd_link_info *, |
| struct bfd_link_order *, bfd_byte *, |
| boolean, asymbol **)); |
| |
| * Menu: |
| |
| * Memory Usage:: |
| * Initialization:: |
| * Sections:: |
| * Symbols:: |
| * Archives:: |
| * Formats:: |
| * Relocations:: |
| * Core Files:: |
| * Targets:: |
| * Architectures:: |
| * Opening and Closing:: |
| * Internal:: |
| * File Caching:: |
| * Linker Functions:: |
| * Hash Tables:: |
| |
| |
| File: bfd.info, Node: Memory Usage, Next: Initialization, Prev: BFD front end, Up: BFD front end |
| |
| Memory usage |
| ============ |
| |
| BFD keeps all of its internal structures in obstacks. There is one |
| obstack per open BFD file, into which the current state is stored. When |
| a BFD is closed, the obstack is deleted, and so everything which has |
| been allocated by BFD for the closing file is thrown away. |
| |
| BFD does not free anything created by an application, but pointers |
| into `bfd' structures become invalid on a `bfd_close'; for example, |
| after a `bfd_close' the vector passed to `bfd_canonicalize_symtab' is |
| still around, since it has been allocated by the application, but the |
| data that it pointed to are lost. |
| |
| The general rule is to not close a BFD until all operations dependent |
| upon data from the BFD have been completed, or all the data from within |
| the file has been copied. To help with the management of memory, there |
| is a function (`bfd_alloc_size') which returns the number of bytes in |
| obstacks associated with the supplied BFD. This could be used to select |
| the greediest open BFD, close it to reclaim the memory, perform some |
| operation and reopen the BFD again, to get a fresh copy of the data |
| structures. |
| |
| |
| File: bfd.info, Node: Initialization, Next: Sections, Prev: Memory Usage, Up: BFD front end |
| |
| Initialization |
| ============== |
| |
| These are the functions that handle initializing a BFD. |
| |
| `bfd_init' |
| .......... |
| |
| *Synopsis* |
| void bfd_init(void); |
| *Description* |
| This routine must be called before any other BFD function to initialize |
| magical internal data structures. |
| |
| |
| File: bfd.info, Node: Sections, Next: Symbols, Prev: Initialization, Up: BFD front end |
| |
| Sections |
| ======== |
| |
| The raw data contained within a BFD is maintained through the |
| section abstraction. A single BFD may have any number of sections. It |
| keeps hold of them by pointing to the first; each one points to the |
| next in the list. |
| |
| Sections are supported in BFD in `section.c'. |
| |
| * Menu: |
| |
| * Section Input:: |
| * Section Output:: |
| * typedef asection:: |
| * section prototypes:: |
| |
| |
| File: bfd.info, Node: Section Input, Next: Section Output, Prev: Sections, Up: Sections |
| |
| Section input |
| ------------- |
| |
| When a BFD is opened for reading, the section structures are created |
| and attached to the BFD. |
| |
| Each section has a name which describes the section in the outside |
| world--for example, `a.out' would contain at least three sections, |
| called `.text', `.data' and `.bss'. |
| |
| Names need not be unique; for example a COFF file may have several |
| sections named `.data'. |
| |
| Sometimes a BFD will contain more than the "natural" number of |
| sections. A back end may attach other sections containing constructor |
| data, or an application may add a section (using `bfd_make_section') to |
| the sections attached to an already open BFD. For example, the linker |
| creates an extra section `COMMON' for each input file's BFD to hold |
| information about common storage. |
| |
| The raw data is not necessarily read in when the section descriptor |
| is created. Some targets may leave the data in place until a |
| `bfd_get_section_contents' call is made. Other back ends may read in |
| all the data at once. For example, an S-record file has to be read |
| once to determine the size of the data. An IEEE-695 file doesn't |
| contain raw data in sections, but data and relocation expressions |
| intermixed, so the data area has to be parsed to get out the data and |
| relocations. |
| |
| |
| File: bfd.info, Node: Section Output, Next: typedef asection, Prev: Section Input, Up: Sections |
| |
| Section output |
| -------------- |
| |
| To write a new object style BFD, the various sections to be written |
| have to be created. They are attached to the BFD in the same way as |
| input sections; data is written to the sections using |
| `bfd_set_section_contents'. |
| |
| Any program that creates or combines sections (e.g., the assembler |
| and linker) must use the `asection' fields `output_section' and |
| `output_offset' to indicate the file sections to which each section |
| must be written. (If the section is being created from scratch, |
| `output_section' should probably point to the section itself and |
| `output_offset' should probably be zero.) |
| |
| The data to be written comes from input sections attached (via |
| `output_section' pointers) to the output sections. The output section |
| structure can be considered a filter for the input section: the output |
| section determines the vma of the output data and the name, but the |
| input section determines the offset into the output section of the data |
| to be written. |
| |
| E.g., to create a section "O", starting at 0x100, 0x123 long, |
| containing two subsections, "A" at offset 0x0 (i.e., at vma 0x100) and |
| "B" at offset 0x20 (i.e., at vma 0x120) the `asection' structures would |
| look like: |
| |
| section name "A" |
| output_offset 0x00 |
| size 0x20 |
| output_section -----------> section name "O" |
| | vma 0x100 |
| section name "B" | size 0x123 |
| output_offset 0x20 | |
| size 0x103 | |
| output_section --------| |
| |
| Link orders |
| ----------- |
| |
| The data within a section is stored in a "link_order". These are |
| much like the fixups in `gas'. The link_order abstraction allows a |
| section to grow and shrink within itself. |
| |
| A link_order knows how big it is, and which is the next link_order |
| and where the raw data for it is; it also points to a list of |
| relocations which apply to it. |
| |
| The link_order is used by the linker to perform relaxing on final |
| code. The compiler creates code which is as big as necessary to make |
| it work without relaxing, and the user can select whether to relax. |
| Sometimes relaxing takes a lot of time. The linker runs around the |
| relocations to see if any are attached to data which can be shrunk, if |
| so it does it on a link_order by link_order basis. |
| |