diff options
Diffstat (limited to 'bfd/doc/bfdinfo')
| -rwxr-xr-x | bfd/doc/bfdinfo | 1281 |
1 files changed, 0 insertions, 1281 deletions
diff --git a/bfd/doc/bfdinfo b/bfd/doc/bfdinfo deleted file mode 100755 index 5bb06ff..0000000 --- a/bfd/doc/bfdinfo +++ /dev/null @@ -1,1281 +0,0 @@ -Info file bfdinfo, produced by Makeinfo, -*- Text -*- from input file -bfd.texinfo. - - 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: bfdinfo, Node: Top, Next: Overview, Prev: (dir), Up: (dir) - - This file documents the binary file descriptor library libbfd. - -* Menu: - -* Overview:: Overview of BFD -* History:: History of BFD -* Backends:: Backends -* Porting:: Porting -* Future:: Future -* Index:: Index - -BFD body: -* Memory usage:: -* Sections:: -* Symbols:: -* Archives:: -* Formats:: -* Relocations:: -* Core Files:: -* Targets:: -* Architecturs:: -* Opening and Closing:: -* Internal:: -* File Caching:: - -BFD backends: -* a.out backends:: -* coff backends:: - - -File: bfdinfo, Node: Overview, Next: History, Prev: Top, Up: Top - -Introduction -************ - - Simply put, BFD is a package which allows applications to use the -same routines to operate on object files whatever the object file -format. A different 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 many back ends. - - * memory, and various canonical data structures. The front end also - decides which back end to use, and when to call back end routines. - - * 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. - - -File: bfdinfo, Node: History, Next: How It Works, Prev: Overview, Up: Top - -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 -Cygnus 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 Steve Chamberlain (steve@cygnus.com), -John Gilmore (gnu@cygnus.com), K. Richard Pixley (rich@cygnus.com) and -David Wallace (gumby@cygnus.com) at Cygnus Support in Palo Alto, -California. - - -File: bfdinfo, Node: How It Works, Next: History, Prev: Porting, Up: Top - -How It Works -============ - - 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 -`include/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 `bfd'_. - - For example, this sequence would do 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); - } - - lisp - - The abstraction used within BFD is that an object file has a header, -a number of sections containing raw data, a set of relocations, and -some symbol information. 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. - -What BFD Version 1 Can Do -========================= - - 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 the memory pointer to the relevant BFD back end -routine 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 which takes the newly created symbol -table and converts it into the chosen output format. - - -File: bfdinfo, Node: BFD information loss, Next: Mechanism, Prev: BFD outline, Up: BFD - -Information Loss ----------------- - - *Some information is lost due to the nature of the file format.* -The output targets supported by BFD do not provide identical -facilities, and information which may 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 -(eg `a.out') or has sections without names (eg 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, this mechanism is very -useful. There is no information lost for this reason 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: bfdinfo, Node: Mechanism, Prev: BFD information loss, Up: BFD - -Mechanism ---------- - - The greatest potential for loss of information is when there is -least overlap between the information provided by the source format, -that stored by the canonical format, and the information needed by the -destination format. A brief description of the canonical form may help -you appreciate what kinds of data you can count on preserving across -conversions. - -*files* - Information on target machine architecture, particular - implementation and format type are stored on a per-file basis. - Other information includes a demand pageable bit and a write - protected bit. Note that 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 linked with one another. - -*sections* - Each section in the input file contains the name of the section, - the original address in the object file, various flags, size and - alignment information and pointers into other BFD data structures. - -*symbols* - Each symbol contains a pointer to 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, the back end relocates all - symbols to make them relative to the base of the section where - they were defined. This ensures that each symbol points to its - containing section. Each symbol also has a varying amount of - hidden data to contain private data for the BFD back end. Since - the symbol points to the original file, the private data format - for that symbol is accessible. `gld' 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 effectively by message - passing through the relocation type descriptor and symbol - pointer. It allows relocations to be performed on output data - using a relocation method 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 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 divination of 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: bfdinfo, Node: BFD front end, Next: BFD back end, Prev: Mechanism, Up: Top - -BFD front end -************* - -typedef bfd -=========== - - Pointers to bfd structs are the cornerstone of any application using -`libbfd'. References though the BFD and to data in the BFD give the -entire BFD functionality. - - Here is the BFD struct itself. This contains the major data about -the file, and contains 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. - - 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. - - char *iostream; - - Is the file being cached *Note File Caching::. - - boolean cacheable; - - Marks whether there was a default target specified when the BFD was -opened. This is used to select what matching algorithm to use to chose -the back end. - - boolean target_defaulted; - - The caching routines use these to maintain a least-recently-used -list of BFDs (*note File Caching::.). - - 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: - - boolean opened_once; - - boolean mtime_set; - - File modified time - - long mtime; - - Reserved for an unimplemented file locking extension. - - int ifd; - - The format which belongs to the BFD. - - 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 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 - - struct symbol_cache_entry **outsymbols; - - Architecture of object machine, eg m68k - - enum bfd_architecture obj_arch; - - Particular machine within arch, e.g. 68010 - - unsigned long obj_machine; - - Stuff only useful for archives: - - PTR arelt_data; - struct _bfd *my_archive; - struct _bfd *next; - struct _bfd *archive_head; - boolean has_armap; - - Used by the back end to hold private data. - - PTR tdata; - - Used by the application to hold private data - - PTR usrdata; - - Where all the allocated stuff under this BFD goes (*note Memory -Usage::.). - - struct obstack memory; - }; - -`bfd_set_start_address' -....................... - - Marks the entry point of an output BFD. Returns `true' on success, -`false' otherwise. - - boolean bfd_set_start_address(bfd *, bfd_vma); - -`bfd_get_mtime' -............... - - Return cached file modification time (e.g. as read from archive -header for archive members, or from file system if we have been called -before); else determine modify time, cache it, and return it. - - long bfd_get_mtime(bfd *); - -`stuff' -....... - - - - #define bfd_sizeof_headers(abfd, reloc) \ - BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc)) - - #define bfd_find_nearest_line(abfd, section, symbols, offset, filename_ptr, func, line_ptr) \ - BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, section, symbols, offset, filename_ptr, func, line_ptr)) - - #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_coff_swap_aux_in(a,e,t,c,i) \ - BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i)) - - #define bfd_coff_swap_sym_in(a,e,i) \ - BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i)) - - #define bfd_coff_swap_lineno_in(a,e,i) \ - BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i)) - - lisp - - -File: bfdinfo, Node: Memory Usage, Next: Sections, Prev: bfd, Up: Top - -Memory Usage -============ - - BFD keeps all 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 libbfd for the closing file will be thrown away. - - BFD will not free anything created by an application, but pointers -into `bfd' structures will be invalidated on a `bfd_close'; for -example, after a `bfd_close' the vector passed to -`bfd_canonicalize_symtab' will still be around, since it has been -allocated by the application, but the data that it pointed to will be -lost. - - The general rule is not to 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: bfdinfo, Node: Sections, Next: Symbols, Prev: Memory Usage, Up: Top - -Sections -======== - - Sections are supported in BFD in `section.c'. - - The raw data contained within a BFD is maintained through the -section abstraction. A single BFD may have any number of sections, -and keeps hold of them by pointing to the first, each one points to -the next in the list. - -* Menu: - -* Section Input:: -* Section Output:: -* typedef asection:: -* section prototypes:: - - -File: bfdinfo, Node: Section Input, Next: Section Output, 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'. - - 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 a supernumary section `COMMON' for each input file's BFD to -hold information about common storage. - - The raw data is not necessarily read in at the same time as 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: bfdinfo, 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'. - - The linker uses the fields `output_section' and `output_offset' to -create an output file. - - The data to be written comes from input sections attached 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. - - Eg to create a section "O", starting at 0x100, 0x123 long, -containing two subsections, "A" at offset 0x0 (ie at vma 0x100) and -"B" at offset 0x20 (ie at vma 0x120) the 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 --------| - - lisp - - -File: bfdinfo, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections - -typedef asection ----------------- - - The shape of a section struct: - - 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; - - The next section in the list belonging to the BFD, or NULL. - - struct sec *next; - - The field flags contains attributes of the section. Some of these -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 loaded. This -would 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 -would be clear for a .bss section - - #define SEC_LOAD 0x002 - - The section contains data still to be relocated, so there will be -some relocation information too. - - #define SEC_RELOC 0x004 - - Obsolete - - #define SEC_BALIGN 0x008 - - 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 (eg -`__CTOR_LIST__'), attaches the symbol to it and builds a relocation. -To build the lists of constructors, all the linker has to to is -catenate all the sections called `__CTOR_LIST__' and relocte 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 -.. - - #define SEC_CONSTRUCTOR_TEXT 0x1100 - - #define SEC_CONSTRUCTOR_DATA 0x2100 - - #define SEC_CONSTRUCTOR_BSS 0x3100 - - The section has contents - a bss 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 not to output sections containing this -flag even if they have information which would normally be written. - - #define SEC_NEVER_LOAD 0x400 - - The base address of the section in the address space of the target. - - bfd_vma vma; - - The size of the section in bytes of the loaded section. This -contains a value even if the section has no contents (eg, the size of -`.bss'). - - bfd_size_type 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. -Eg, 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 - eg 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; - - Which section is it 0..nth - - int index; - - 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; - - struct lang_output_section *otheruserdata; - - 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 - - unsigned 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; - - } asection ; - - -File: bfdinfo, Node: section prototypes, Next: Section, Prev: typedef section, Up: Sections - -section prototypes ------------------- - -`bfd_get_section_by_name' -......................... - - Runs through the provided ABFD and returns the `asection' who's -name matches that provided, otherwise NULL. *Note Sections::, for more -information. - - asection * bfd_get_section_by_name(bfd *abfd, CONST char *name); - -`bfd_make_section' -.................. - - This function creates a new empty section called NAME and attaches -it to the end of the chain of sections for the BFD supplied. An -attempt to create a section with a name which is already in use, -returns the old section by that name instead. - - Possible errors are: - -`invalid_operation' - If output has already started for this BFD. - -`no_memory' - If obstack alloc fails. - - asection * bfd_make_section(bfd *, CONST char *name); - -`bfd_set_section_flags' -....................... - - Attempts to set the attributes of the section named in the BFD -supplied to the value. Returns true on success, false on error. -Possible error returns are: - -`invalid operation' - The section cannot have one or more of the attributes requested. - For example, a .bss section in `a.out' may not have the - `SEC_HAS_CONTENTS' field set. - - boolean bfd_set_section_flags(bfd *, asection *, flagword); - -`bfd_map_over_sections' -....................... - - Calls the provided function FUNC for each section attached to the -BFD ABFD, passing OBJ as an argument. The function will be called as -if by - - func(abfd, the_section, obj); - - void bfd_map_over_sections(bfd *abfd, void (*func)(), PTR obj); - - This is the prefered method for iterating over sections, an -alternative would be to use a loop: - - section *p; - for (p = abfd->sections; p != NULL; p = p->next) - func(abfd, p, ...) - -`bfd_set_section_size' -...................... - - Sets SECTION to the size VAL. If the operation is ok, then `true' -is returned, else `false'. - - Possible error returns: - -`invalid_operation' - Writing has started to the BFD, so setting the size is invalid - - boolean bfd_set_section_size(bfd *, asection *, bfd_size_type val); - -`bfd_set_section_contents' -.......................... - - Sets the contents of the section SECTION in BFD ABFD to the data -starting in memory at DATA. The data is written to the output section -starting at offset OFFSET for COUNT bytes. - - Normally `true' is returned, else `false'. Possible error returns -are: - -`no_contents' - The output section does not have the `SEC_HAS_CONTENTS' - attribute, so nothing can be written to it. - -`and some more too' - This routine is front end to the back end function -`_bfd_set_section_contents'. - - boolean bfd_set_section_contents(bfd *abfd, - asection *section, - PTR data, - file_ptr offset, - bfd_size_type count); - -`bfd_get_section_contents' -.......................... - - This function reads data from SECTION in BFD ABFD into memory -starting at LOCATION. The data is read at an offset of OFFSET from the -start of the input section, and is read for COUNT bytes. - - If the contents of a constuctor with the `SEC_CONSTUCTOR' flag set -are requested, then the LOCATION is filled with zeroes. - - If no errors occur, `true' is returned, else `false'. Possible -errors are: - -`unknown yet' - boolean bfd_get_section_contents(bfd *abfd, asection *section, PTR location, - file_ptr offset, bfd_size_type count); - - -File: bfdinfo, Node: Symbols, Next: Archives, Prev: Sections, Up: To - -Symbols -======= - - BFD trys to maintain as much symbol information as it can when it -moves information from file to file. BFD passes information to -applications though the `asymbol' structure. When the application -requests the symbol table, BFD reads the table in the native form and -translates parts of it into the internal format. To maintain more than -the infomation passed to applications some targets keep some -information 'behind the sceans', in a structure only the particular -back end knows about. For example, the coff back end keeps the -original symbol table structure as well as the canonical structure -when a BFD is read in. On output, the coff back end can reconstruct -the output symbol table so that no information is lost, even -information unique to coff which BFD doesn't know or understand. If a -coff symbol table was read, but was written through an a.out back end, -all the coff specific information would be lost. (.. until BFD 2 :). - - The symbol table of a BFD is not necessarily read in until a -canonicalize request is made. Then the BFD back end fills in a table -provided by the application with pointers to the canonical information. - - To output symbols, the application provides BFD with a table of -pointers to pointers to `asymbol's. This allows applications like the -linker to output a symbol as read, since the 'behind the sceens' -information will be still available. - -* Menu: - -* Reading Symbols:: -* Writing Symbols:: -* typedef asymbol:: -* symbol handling functions:: - - -File: bfdinfo, Node: Reading Symbols, Next: Writing Symbols, Prev: Symbols, Up: Symbols - -Reading Symbols ---------------- - - There are two stages to reading a symbol table from a BFD; -allocating storage, and the actual reading process. This is an excerpt -from an appliction which reads the symbol table: - - - unsigned int storage_needed; - asymbol **symbol_table; - unsigned int number_of_symbols; - unsigned int i; - - storage_needed = get_symtab_upper_bound (abfd); - - if (storage_needed == 0) { - return ; - } - symbol_table = (asymbol **) malloc (storage_needed); - ... - number_of_symbols = - bfd_canonicalize_symtab (abfd, symbol_table); - - for (i = 0; i < number_of_symbols; i++) { - process_symbol (symbol_table[i]); - } - - lisp - - All storage for the symbols themselves is in an obstack connected to -the BFD, and is freed when the BFD is closed. - - -File: bfdinfo, Node: Writing Symbols, Next: typedef asymbol, Prev: Reading Symbols, Up: Symbols - -Writing Symbols ---------------- - - Writing of a symbol table is automatic when a BFD open for writing -is closed. The application attaches a vector of pointers to pointers -to symbols to the BFD being written, and fills in the symbol count. -The close and cleanup code reads through the table provided and -performs all the necessary operations. The outputing code must always -be provided with an 'owned' symbol; one which has come from another -BFD, or one which has been created using `bfd_make_empty_symbol'. - - An example showing the creation of a symbol table with only one -element: - - - #include "bfd.h" - main() - { - bfd *abfd; - asymbol *ptrs[2]; - asymbol *new; - - abfd = bfd_openw("foo","a.out-sunos-big"); - bfd_set_format(abfd, bfd_object); - new = bfd_make_empty_symbol(abfd); - new->name = "dummy_symbol"; - new->section = (asection *)0; - new->flags = BSF_ABSOLUTE | BSF_GLOBAL; - new->value = 0x12345; - - ptrs[0] = new; - ptrs[1] = (asymbol *)0; - - bfd_set_symtab(abfd, ptrs, 1); - bfd_close(abfd); - } - - ./makesym - nm foo - 00012345 A dummy_symbol - - lisp - - Many formats cannot represent arbitary symbol information; for -instance the `a.out' object format does not allow an arbitary number -of sections. A symbol pointing to a section which is not one of -`.text', `.data' or `.bss' cannot be described. - - -File: bfdinfo, Node: typedef asymbol, Next: symbol handling functions, Prev: Writing Symbols, Up: Symbols - -typedef asymbol ---------------- - - An `asymbol' has the form: - - typedef struct symbol_cache_entry - { - - A pointer to the BFD which owns the symbol. This information is -necessary so that a back end can work out what additional (invisible to -the application writer) information is carried with the symbol. - - struct _bfd *the_bfd; - - The text of the symbol. The name is left alone, and not copied - the -application may not alter it. - - CONST char *name; - - The value of the symbol. - - symvalue value; - - Attributes of a symbol: - - #define BSF_NO_FLAGS 0x00 - - The symbol has local scope; `static' in `C'. The value is the -offset into the section of the data. - - #define BSF_LOCAL 0x01 - - The symbol has global scope; initialized data in `C'. The value is -the offset into the section of the data. - - #define BSF_GLOBAL 0x02 - - Obsolete - - #define BSF_IMPORT 0x04 - - The symbol has global scope, and is exported. The value is the -offset into the section of the data. - - #define BSF_EXPORT 0x08 - - The symbol is undefined. `extern' in `C'. The value has no meaning. - - #define BSF_UNDEFINED 0x10 - - The symbol is common, initialized to zero; default in `C'. The -value is the size of the object in bytes. - - #define BSF_FORT_COMM 0x20 - - A normal `C' symbol would be one of: `BSF_LOCAL', `BSF_FORT_COMM', -`BSF_UNDEFINED' or `BSF_EXPORT|BSD_GLOBAL' - - The symbol is a debugging record. The value has an arbitary meaning. - - #define BSF_DEBUGGING 0x40 - - The symbol has no section attached, any value is the actual value -and is not a relative offset to a section. - - #define BSF_ABSOLUTE 0x80 - - Used by the linker - - #define BSF_KEEP 0x10000 - #define BSF_KEEP_G 0x80000 - - Unused - - #define BSF_WEAK 0x100000 - #define BSF_CTOR 0x200000 - #define BSF_FAKE 0x400000 - - The symbol used to be a common symbol, but now it is allocated. - - #define BSF_OLD_COMMON 0x800000 - - The default value for common data. - - #define BFD_FORT_COMM_DEFAULT_VALUE 0 - - In some files the type of a symbol sometimes alters its location in -an output file - ie in coff a `ISFCN' symbol which is also `C_EXT' -symbol appears where it was declared and not at the end of a section. -This bit is set by the target BFD part to convey this information. - - #define BSF_NOT_AT_END 0x40000 - - Signal that the symbol is the label of constructor section. - - #define BSF_CONSTRUCTOR 0x1000000 - - Signal that the symbol is a warning symbol. If the symbol is a -warning symbol, then the value field (I know this is tacky) will point -to the asymbol which when referenced will cause the warning. - - #define BSF_WARNING 0x2000000 - - Signal that the symbol is indirect. The value of the symbol is a -pointer to an undefined asymbol which contains the name to use instead. - - #define BSF_INDIRECT 0x4000000 - - flagword flags; - - A pointer to the section to which this symbol is relative, or 0 if -the symbol is absolute or undefined. Note that it is not sufficient to -set this location to 0 to mark a symbol as absolute - the flag -`BSF_ABSOLUTE' must be set also. - - struct sec *section; - - Back end special data. This is being phased out in favour of making -this a union. - - PTR udata; - } asymbol; - - -File: bfdinfo, Node: symbol handling functions, Next: Symbols, Prev: typedef asymbol, Up: Symbols - -Symbol Handling Functions -------------------------- - -`get_symtab_upper_bound' -........................ - - Returns the number of bytes required in a vector of pointers to -`asymbols' for all the symbols in the supplied BFD, including a -terminal NULL pointer. If there are no symbols in the BFD, then 0 is -returned. - - - #define get_symtab_upper_bound(abfd) \ - BFD_SEND (abfd, _get_symtab_upper_bound, (abfd)) - - lisp - -`bfd_canonicalize_symtab' -......................... - - Supplied a BFD and a pointer to an uninitialized vector of pointers. -This reads in the symbols from the BFD, and fills in the table with -pointers to the symbols, and a trailing NULL. The routine returns the -actual number of symbol pointers not including the NULL. - - - #define bfd_canonicalize_symtab(abfd, location) \ - BFD_SEND (abfd, _bfd_canonicalize_symtab,\ - (abfd, location)) - - lisp - -`bfd_set_symtab' -................ - - Provided a table of pointers to to symbols and a count, writes to -the output BFD the symbols when closed. - - boolean bfd_set_symtab(bfd *, asymbol **, unsigned int ); - -`bfd_print_symbol_vandf' -........................ - - Prints the value and flags of the symbol supplied to the stream -file. - - void bfd_print_symbol_vandf(PTR file, asymbol *symbol); - -`bfd_make_empty_symbol' -....................... - - This function creates a new `asymbol' structure for the BFD, and -returns a pointer to it. - - This routine is necessary, since each back end has private -information surrounding the `asymbol'. Building your own `asymbol' and -pointing to it will not create the private information, and will cause -problems later on. - - - #define bfd_make_empty_symbol(abfd) \ - BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd)) - - lisp - - -File: bfdinfo, Node: Archives, Next: Formats, Prev: Symbols, Up: Top - -Archives -======== - - Gumby, you promised to write this bit... - - Archives are supported in BFD in `archive.c'. - - An archive is represented internally just like another BFD, with a -pointer to a chain of contained BFDs. Archives can be created by -opening BFDs, linking them together and attaching them as children to -another BFD and then closing the parent BFD. - -`bfd_get_next_mapent' -..................... - - What this does - - symindex bfd_get_next_mapent(bfd *, symindex, carsym **); - -`bfd_set_archive_head' -...................... - - Used whilst processing archives. Sets the head of the chain of BFDs -contained in an archive to NEW_HEAD. (see chapter on archives) - - boolean bfd_set_archive_head(bfd *output, bfd *new_head); - -`bfd_get_elt_at_index' -...................... - - Return the sub bfd contained within the archive at archive index n. - - bfd * bfd_get_elt_at_index(bfd *, int); - -`bfd_openr_next_archived_file' -.............................. - - Initially provided a BFD containing an archive and NULL, opens a BFD -on the first contained element and returns that. Subsequent calls to -bfd_openr_next_archived_file should pass the archive and the previous -return value to return a created BFD to the next contained element. -NULL is returned when there are no more. - - bfd* bfd_openr_next_archived_file(bfd *archive, bfd *previous); - - -File: bfdinfo, Node: Formats, Next: Relocations, Prev: Archives, Up: Top - -File Formats -============ - - A format is a BFD concept of high level file contents. The formats -supported by BFD are: - -`bfd_object' - The BFD may contain data, symbols, relocations and debug info. - -`bfd_archive' - The
\ No newline at end of file |