diff options
Diffstat (limited to 'gnu/usr.bin/binutils/bfd/doc/bfd.info-1')
| -rw-r--r-- | gnu/usr.bin/binutils/bfd/doc/bfd.info-1 | 1306 |
1 files changed, 0 insertions, 1306 deletions
diff --git a/gnu/usr.bin/binutils/bfd/doc/bfd.info-1 b/gnu/usr.bin/binutils/bfd/doc/bfd.info-1 deleted file mode 100644 index cb26d46ed74..00000000000 --- a/gnu/usr.bin/binutils/bfd/doc/bfd.info-1 +++ /dev/null @@ -1,1306 +0,0 @@ -This is Info file bfd.info, produced by Makeinfo-1.64 from the input -file ./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 Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, subject to the -terms of the GNU General Public License, which includes the provision -that the entire resulting derived work is distributed under the terms -of a permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions. - - -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 -* 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 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. -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_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_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. - -File: bfd.info, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections - -typedef asection ----------------- - -Here is the section structure: -. - typedef struct sec - { - /* The name of the section; the name isn't a copy, the pointer is - the same as that passed to bfd_make_section. */ - - CONST char *name; - - /* Which section is it; 0..nth. */ - - int index; - - /* The next section in the list belonging to the BFD, or NULL. */ - - struct sec *next; - - /* The field flags contains attributes of the section. Some - flags are read in from the object file, and some are - synthesized from other information. */ - - flagword flags; - - #define SEC_NO_FLAGS 0x000 - - /* Tells the OS to allocate space for this section when loading. - This is clear for a section containing debug information - only. */ - #define SEC_ALLOC 0x001 - - /* Tells the OS to load the section from the file when loading. - This is clear for a .bss section. */ - #define SEC_LOAD 0x002 - - /* The section contains data still to be relocated, so there is - some relocation information too. */ - #define SEC_RELOC 0x004 - - #if 0 /* Obsolete ? */ - #define SEC_BALIGN 0x008 - #endif - - /* A signal to the OS that the section contains read only - data. */ - #define SEC_READONLY 0x010 - - /* The section contains code only. */ - #define SEC_CODE 0x020 - - /* The section contains data only. */ - #define SEC_DATA 0x040 - - /* The section will reside in ROM. */ - #define SEC_ROM 0x080 - - /* The section contains constructor information. This section - type is used by the linker to create lists of constructors and - destructors used by `g++'. When a back end sees a symbol - which should be used in a constructor list, it creates a new - section for the type of name (e.g., `__CTOR_LIST__'), attaches - the symbol to it, and builds a relocation. To build the lists - of constructors, all the linker has to do is catenate all the - sections called `__CTOR_LIST__' and relocate the data - contained within - exactly the operations it would peform on - standard data. */ - #define SEC_CONSTRUCTOR 0x100 - - /* The section is a constuctor, and should be placed at the - end of the text, data, or bss section(?). */ - #define SEC_CONSTRUCTOR_TEXT 0x1100 - #define SEC_CONSTRUCTOR_DATA 0x2100 - #define SEC_CONSTRUCTOR_BSS 0x3100 - - /* The section has contents - a data section could be - `SEC_ALLOC' | `SEC_HAS_CONTENTS'; a debug section could be - `SEC_HAS_CONTENTS' */ - #define SEC_HAS_CONTENTS 0x200 - - /* An instruction to the linker to not output the section - even if it has information which would normally be written. */ - #define SEC_NEVER_LOAD 0x400 - - /* The section is a COFF shared library section. This flag is - only for the linker. If this type of section appears in - the input file, the linker must copy it to the output file - without changing the vma or size. FIXME: Although this - was originally intended to be general, it really is COFF - specific (and the flag was renamed to indicate this). It - might be cleaner to have some more general mechanism to - allow the back end to control what the linker does with - sections. */ - #define SEC_COFF_SHARED_LIBRARY 0x800 - - /* The section contains common symbols (symbols may be defined - multiple times, the value of a symbol is the amount of - space it requires, and the largest symbol value is the one - used). Most targets have exactly one of these (which we - translate to bfd_com_section_ptr), but ECOFF has two. */ - #define SEC_IS_COMMON 0x8000 - - /* The section contains only debugging information. For - example, this is set for ELF .debug and .stab sections. - strip tests this flag to see if a section can be - discarded. */ - #define SEC_DEBUGGING 0x10000 - - /* The contents of this section are held in memory pointed to - by the contents field. This is checked by - bfd_get_section_contents, and the data is retrieved from - memory if appropriate. */ - #define SEC_IN_MEMORY 0x20000 - - /* The contents of this section are to be excluded by the - linker for executable and shared objects unless those - objects are to be further relocated. */ - #define SEC_EXCLUDE 0x40000 - - /* The contents of this section are to be sorted by the - based on the address specified in the associated symbol - table. */ - #define SEC_SORT_ENTRIES 0x80000 - - /* When linking, duplicate sections of the same name should be - discarded, rather than being combined into a single section as - is usually done. This is similar to how common symbols are - handled. See SEC_LINK_DUPLICATES below. */ - #define SEC_LINK_ONCE 0x100000 - - /* If SEC_LINK_ONCE is set, this bitfield describes how the linker - should handle duplicate sections. */ - #define SEC_LINK_DUPLICATES 0x600000 - - /* This value for SEC_LINK_DUPLICATES means that duplicate - sections with the same name should simply be discarded. */ - #define SEC_LINK_DUPLICATES_DISCARD 0x0 - - /* This value for SEC_LINK_DUPLICATES means that the linker - should warn if there are any duplicate sections, although - it should still only link one copy. */ - #define SEC_LINK_DUPLICATES_ONE_ONLY 0x200000 - - /* This value for SEC_LINK_DUPLICATES means that the linker - should warn if any duplicate sections are a different size. */ - #define SEC_LINK_DUPLICATES_SAME_SIZE 0x400000 - - /* This value for SEC_LINK_DUPLICATES means that the linker - should warn if any duplicate sections contain different - contents. */ - #define SEC_LINK_DUPLICATES_SAME_CONTENTS 0x600000 - - /* This section was created by the linker as part of dynamic - relocation or other arcane processing. It is skipped when - going through the first-pass output, trusting that someone - else up the line will take care of it later. */ - #define SEC_LINKER_CREATED 0x800000 - - /* End of section flags. */ - - /* Some internal packed boolean fields. */ - - /* See the vma field. */ - unsigned int user_set_vma : 1; - - /* Whether relocations have been processed. */ - unsigned int reloc_done : 1; - - /* A mark flag used by some of the linker backends. */ - unsigned int linker_mark : 1; - - /* End of internal packed boolean fields. */ - - /* The virtual memory address of the section - where it will be - at run time. The symbols are relocated against this. The - user_set_vma flag is maintained by bfd; if it's not set, the - backend can assign addresses (for example, in `a.out', where - the default address for `.data' is dependent on the specific - target and various flags). */ - - bfd_vma vma; - - /* The load address of the section - where it would be in a - rom image; really only used for writing section header - information. */ - - bfd_vma lma; - - /* The size of the section in bytes, as it will be output. - contains a value even if the section has no contents (e.g., the - size of `.bss'). This will be filled in after relocation */ - - bfd_size_type _cooked_size; - - /* The original size on disk of the section, in bytes. Normally this - value is the same as the size, but if some relaxing has - been done, then this value will be bigger. */ - - bfd_size_type _raw_size; - - /* If this section is going to be output, then this value is the - offset into the output section of the first byte in the input - section. E.g., if this was going to start at the 100th byte in - the output section, this value would be 100. */ - - bfd_vma output_offset; - - /* The output section through which to map on output. */ - - struct sec *output_section; - - /* The alignment requirement of the section, as an exponent of 2 - - e.g., 3 aligns to 2^3 (or 8). */ - - unsigned int alignment_power; - - /* If an input section, a pointer to a vector of relocation - records for the data in this section. */ - - struct reloc_cache_entry *relocation; - - /* If an output section, a pointer to a vector of pointers to - relocation records for the data in this section. */ - - struct reloc_cache_entry **orelocation; - - /* The number of relocation records in one of the above */ - - unsigned reloc_count; - - /* Information below is back end specific - and not always used - or updated. */ - - /* File position of section data */ - - file_ptr filepos; - - /* File position of relocation info */ - - file_ptr rel_filepos; - - /* File position of line data */ - - file_ptr line_filepos; - - /* Pointer to data for applications */ - - PTR userdata; - - /* If the SEC_IN_MEMORY flag is set, this points to the actual - contents. */ - unsigned char *contents; - - /* Attached line number information */ - - alent *lineno; - - /* Number of line number records */ - - unsigned int lineno_count; - - /* When a section is being output, this value changes as more - linenumbers are written out */ - - file_ptr moving_line_filepos; - - /* What the section number is in the target world */ - - int target_index; - - PTR used_by_bfd; - - /* If this is a constructor section then here is a list of the - relocations created to relocate items within it. */ - - struct relent_chain *constructor_chain; - - /* The BFD which owns the section. */ - - bfd *owner; - - /* A symbol which points at this section only */ - struct symbol_cache_entry *symbol; - struct symbol_cache_entry **symbol_ptr_ptr; - - struct bfd_link_order *link_order_head; - struct bfd_link_order *link_order_tail; - } asection ; - - /* These sections are global, and are managed by BFD. The application - and target back end are not permitted to change the values in - these sections. New code should use the section_ptr macros rather - than referring directly to the const sections. The const sections - may eventually vanish. */ - #define BFD_ABS_SECTION_NAME "*ABS*" - #define BFD_UND_SECTION_NAME "*UND*" - #define BFD_COM_SECTION_NAME "*COM*" - #define BFD_IND_SECTION_NAME "*IND*" - - /* the absolute section */ - extern const asection bfd_abs_section; - #define bfd_abs_section_ptr ((asection *) &bfd_abs_section) - #define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr) - /* Pointer to the undefined section */ - extern const asection bfd_und_section; - #define bfd_und_section_ptr ((asection *) &bfd_und_section) - #define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr) - /* Pointer to the common section */ - extern const asection bfd_com_section; - #define bfd_com_section_ptr ((asection *) &bfd_com_section) - /* Pointer to the indirect section */ - extern const asection bfd_ind_section; - #define bfd_ind_section_ptr ((asection *) &bfd_ind_section) - #define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr) - - extern const struct symbol_cache_entry * const bfd_abs_symbol; - extern const struct symbol_cache_entry * const bfd_com_symbol; - extern const struct symbol_cache_entry * const bfd_und_symbol; - extern const struct symbol_cache_entry * const bfd_ind_symbol; - #define bfd_get_section_size_before_reloc(section) \ - (section->reloc_done ? (abort(),1): (section)->_raw_size) - #define bfd_get_section_size_after_reloc(section) \ - ((section->reloc_done) ? (section)->_cooked_size: (abort(),1)) - |