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: Internal, Next: File Caching, Prev: Opening and Closing, Up: BFD front end Internal functions ================== *Description* These routines are used within BFD. They are not intended for export, but are documented here for completeness. `bfd_write_bigendian_4byte_int' ............................... *Synopsis* void bfd_write_bigendian_4byte_int(bfd *abfd, int i); *Description* Write a 4 byte integer I to the output BFD ABFD, in big endian order regardless of what else is going on. This is useful in archives. `bfd_put_size' .............. `bfd_get_size' .............. *Description* These macros as used for reading and writing raw data in sections; each access (except for bytes) is vectored through the target format of the BFD and mangled accordingly. The mangling performs any necessary endian translations and removes alignment restrictions. Note that types accepted and returned by these macros are identical so they can be swapped around in macros--for example, `libaout.h' defines `GET_WORD' to either `bfd_get_32' or `bfd_get_64'. In the put routines, VAL must be a `bfd_vma'. If we are on a system without prototypes, the caller is responsible for making sure that is true, with a cast if necessary. We don't cast them in the macro definitions because that would prevent `lint' or `gcc -Wall' from detecting sins such as passing a pointer. To detect calling these with less than a `bfd_vma', use `gcc -Wconversion' on a host with 64 bit `bfd_vma''s. /* Byte swapping macros for user section data. */ #define bfd_put_8(abfd, val, ptr) \ (*((unsigned char *)(ptr)) = (unsigned char)(val)) #define bfd_put_signed_8 \ bfd_put_8 #define bfd_get_8(abfd, ptr) \ (*(unsigned char *)(ptr)) #define bfd_get_signed_8(abfd, ptr) \ ((*(unsigned char *)(ptr) ^ 0x80) - 0x80) #define bfd_put_16(abfd, val, ptr) \ BFD_SEND(abfd, bfd_putx16, ((val),(ptr))) #define bfd_put_signed_16 \ bfd_put_16 #define bfd_get_16(abfd, ptr) \ BFD_SEND(abfd, bfd_getx16, (ptr)) #define bfd_get_signed_16(abfd, ptr) \ BFD_SEND (abfd, bfd_getx_signed_16, (ptr)) #define bfd_put_32(abfd, val, ptr) \ BFD_SEND(abfd, bfd_putx32, ((val),(ptr))) #define bfd_put_signed_32 \ bfd_put_32 #define bfd_get_32(abfd, ptr) \ BFD_SEND(abfd, bfd_getx32, (ptr)) #define bfd_get_signed_32(abfd, ptr) \ BFD_SEND(abfd, bfd_getx_signed_32, (ptr)) #define bfd_put_64(abfd, val, ptr) \ BFD_SEND(abfd, bfd_putx64, ((val), (ptr))) #define bfd_put_signed_64 \ bfd_put_64 #define bfd_get_64(abfd, ptr) \ BFD_SEND(abfd, bfd_getx64, (ptr)) #define bfd_get_signed_64(abfd, ptr) \ BFD_SEND(abfd, bfd_getx_signed_64, (ptr)) `bfd_h_put_size' ................ *Description* These macros have the same function as their `bfd_get_x' bretheren, except that they are used for removing information for the header records of object files. Believe it or not, some object files keep their header records in big endian order and their data in little endian order. /* Byte swapping macros for file header data. */ #define bfd_h_put_8(abfd, val, ptr) \ bfd_put_8 (abfd, val, ptr) #define bfd_h_put_signed_8(abfd, val, ptr) \ bfd_put_8 (abfd, val, ptr) #define bfd_h_get_8(abfd, ptr) \ bfd_get_8 (abfd, ptr) #define bfd_h_get_signed_8(abfd, ptr) \ bfd_get_signed_8 (abfd, ptr) #define bfd_h_put_16(abfd, val, ptr) \ BFD_SEND(abfd, bfd_h_putx16,(val,ptr)) #define bfd_h_put_signed_16 \ bfd_h_put_16 #define bfd_h_get_16(abfd, ptr) \ BFD_SEND(abfd, bfd_h_getx16,(ptr)) #define bfd_h_get_signed_16(abfd, ptr) \ BFD_SEND(abfd, bfd_h_getx_signed_16, (ptr)) #define bfd_h_put_32(abfd, val, ptr) \ BFD_SEND(abfd, bfd_h_putx32,(val,ptr)) #define bfd_h_put_signed_32 \ bfd_h_put_32 #define bfd_h_get_32(abfd, ptr) \ BFD_SEND(abfd, bfd_h_getx32,(ptr)) #define bfd_h_get_signed_32(abfd, ptr) \ BFD_SEND(abfd, bfd_h_getx_signed_32, (ptr)) #define bfd_h_put_64(abfd, val, ptr) \ BFD_SEND(abfd, bfd_h_putx64,(val, ptr)) #define bfd_h_put_signed_64 \ bfd_h_put_64 #define bfd_h_get_64(abfd, ptr) \ BFD_SEND(abfd, bfd_h_getx64,(ptr)) #define bfd_h_get_signed_64(abfd, ptr) \ BFD_SEND(abfd, bfd_h_getx_signed_64, (ptr)) `bfd_log2' .......... *Synopsis* unsigned int bfd_log2(bfd_vma x); *Description* Return the log base 2 of the value supplied, rounded up. E.g., an X of 1025 returns 11.  File: bfd.info, Node: File Caching, Next: Linker Functions, Prev: Internal, Up: BFD front end File caching ============ The file caching mechanism is embedded within BFD and allows the application to open as many BFDs as it wants without regard to the underlying operating system's file descriptor limit (often as low as 20 open files). The module in `cache.c' maintains a least recently used list of `BFD_CACHE_MAX_OPEN' files, and exports the name `bfd_cache_lookup', which runs around and makes sure that the required BFD is open. If not, then it chooses a file to close, closes it and opens the one wanted, returning its file handle. `BFD_CACHE_MAX_OPEN macro' .......................... *Description* The maximum number of files which the cache will keep open at one time. #define BFD_CACHE_MAX_OPEN 10 `bfd_last_cache' ................ *Synopsis* extern bfd *bfd_last_cache; *Description* Zero, or a pointer to the topmost BFD on the chain. This is used by the `bfd_cache_lookup' macro in `libbfd.h' to determine when it can avoid a function call. `bfd_cache_lookup' .................. *Description* Check to see if the required BFD is the same as the last one looked up. If so, then it can use the stream in the BFD with impunity, since it can't have changed since the last lookup; otherwise, it has to perform the complicated lookup function. #define bfd_cache_lookup(x) \ ((x)==bfd_last_cache? \ (FILE*)(bfd_last_cache->iostream): \ bfd_cache_lookup_worker(x)) `bfd_cache_init' ................ *Synopsis* boolean bfd_cache_init (bfd *abfd); *Description* Add a newly opened BFD to the cache. `bfd_cache_close' ................. *Synopsis* boolean bfd_cache_close (bfd *abfd); *Description* Remove the BFD ABFD from the cache. If the attached file is open, then close it too. *Returns* `false' is returned if closing the file fails, `true' is returned if all is well. `bfd_open_file' ............... *Synopsis* FILE* bfd_open_file(bfd *abfd); *Description* Call the OS to open a file for ABFD. Return the `FILE *' (possibly `NULL') that results from this operation. Set up the BFD so that future accesses know the file is open. If the `FILE *' returned is `NULL', then it won't have been put in the cache, so it won't have to be removed from it. `bfd_cache_lookup_worker' ......................... *Synopsis* FILE *bfd_cache_lookup_worker(bfd *abfd); *Description* Called when the macro `bfd_cache_lookup' fails to find a quick answer. Find a file descriptor for ABFD. If necessary, it open it. If there are already more than `BFD_CACHE_MAX_OPEN' files open, it tries to close one first, to avoid running out of file descriptors.  File: bfd.info, Node: Linker Functions, Next: Hash Tables, Prev: File Caching, Up: BFD front end Linker Functions ================ The linker uses three special entry points in the BFD target vector. It is not necessary to write special routines for these entry points when creating a new BFD back end, since generic versions are provided. However, writing them can speed up linking and make it use significantly less runtime memory. The first routine creates a hash table used by the other routines. The second routine adds the symbols from an object file to the hash table. The third routine takes all the object files and links them together to create the output file. These routines are designed so that the linker proper does not need to know anything about the symbols in the object files that it is linking. The linker merely arranges the sections as directed by the linker script and lets BFD handle the details of symbols and relocs. The second routine and third routines are passed a pointer to a `struct bfd_link_info' structure (defined in `bfdlink.h') which holds information relevant to the link, including the linker hash table (which was created by the first routine) and a set of callback functions to the linker proper. The generic linker routines are in `linker.c', and use the header file `genlink.h'. As of this writing, the only back ends which have implemented versions of these routines are a.out (in `aoutx.h') and ECOFF (in `ecoff.c'). The a.out routines are used as examples throughout this section. * Menu: * Creating a Linker Hash Table:: * Adding Symbols to the Hash Table:: * Performing the Final Link::  File: bfd.info, Node: Creating a Linker Hash Table, Next: Adding Symbols to the Hash Table, Prev: Linker Functions, Up: Linker Functions Creating a linker hash table ---------------------------- The linker routines must create a hash table, which must be derived from `struct bfd_link_hash_table' described in `bfdlink.c'. *Note Hash Tables:: for information on how to create a derived hash table. This entry point is called using the target vector of the linker output file. The `_bfd_link_hash_table_create' entry point must allocate and initialize an instance of the desired hash table. If the back end does not require any additional information to be stored with the entries in the hash table, the entry point may simply create a `struct bfd_link_hash_table'. Most likely, however, some additional information will be needed. For example, with each entry in the hash table the a.out linker keeps the index the symbol has in the final output file (this index number is used so that when doing a relocateable link the symbol index used in the output file can be quickly filled in when copying over a reloc). The a.out linker code defines the required structures and functions for a hash table derived from `struct bfd_link_hash_table'. The a.out linker hash table is created by the function `NAME(aout,link_hash_table_create)'; it simply allocates space for the hash table, initializes it, and returns a pointer to it. When writing the linker routines for a new back end, you will generally not know exactly which fields will be required until you have finished. You should simply create a new hash table which defines no additional fields, and then simply add fields as they become necessary.  File: bfd.info, Node: Adding Symbols to the Hash Table, Next: Performing the Final Link, Prev: Creating a Linker Hash Table, Up: Linker Functions Adding symbols to the hash table -------------------------------- The linker proper will call the `_bfd_link_add_symbols' entry point for each object file or archive which is to be linked (typically these are the files named on the command line, but some may also come from the linker script). The entry point is responsible for examining the file. For an object file, BFD must add any relevant symbol information to the hash table. For an archive, BFD must determine which elements of the archive should be used and adding them to the link. The a.out version of this entry point is `NAME(aout,link_add_symbols)'. * Menu: * Differing file formats:: * Adding symbols from an object file:: * Adding symbols from an archive::  File: bfd.info, Node: Differing file formats, Next: Adding symbols from an object file, Prev: Adding Symbols to the Hash Table, Up: Adding Symbols to the Hash Table Differing file formats ...................... Normally all the files involved in a link will be of the same format, but it is also possible to link together different format object files, and the back end must support that. The `_bfd_link_add_symbols' entry point is called via the target vector of the file to be added. This has an important consequence: the function may not assume that the hash table is the type created by the corresponding `_bfd_link_hash_table_create' vector. All the `_bfd_link_add_symbols' function can assume about the hash table is that it is derived from `struct bfd_link_hash_table'. Sometimes the `_bfd_link_add_symbols' function must store some information in the hash table entry to be used by the `_bfd_final_link' function. In such a case the `creator' field of the hash table must be checked to make sure that the hash table was created by an object file of the same format. The `_bfd_final_link' routine must be prepared to handle a hash entry without any extra information added by the `_bfd_link_add_symbols' function. A hash entry without extra information will also occur when the linker script directs the linker to create a symbol. Note that, regardless of how a hash table entry is added, all the fields will be initialized to some sort of null value by the hash table entry initialization function. See `ecoff_link_add_externals' for an example of how to check the `creator' field before saving information (in this case, the ECOFF external symbol debugging information) in a hash table entry.  File: bfd.info, Node: Adding symbols from an object file, Next: Adding symbols from an archive, Prev: Differing file formats, Up: Adding Symbols to the Hash Table Adding symbols from an object file .................................. When the `_bfd_link_add_symbols' routine is passed an object file, it must add all externally visible symbols in that object file to the hash table. The actual work of adding the symbol to the hash table is normally handled by the function `_bfd_generic_link_add_one_symbol'. The `_bfd_link_add_symbols' routine is responsible for reading all the symbols from the object file and passing the correct information to `_bfd_generic_link_add_one_symbol'. The `_bfd_link_add_symbols' routine should not use `bfd_canonicalize_symtab' to read the symbols. The point of providing this routine is to avoid the overhead of converting the symbols into generic `asymbol' structures. `_bfd_generic_link_add_one_symbol' handles the details of combining common symbols, warning about multiple definitions, and so forth. It takes arguments which describe the symbol to add, notably symbol flags, a section, and an offset. The symbol flags include such things as `BSF_WEAK' or `BSF_INDIRECT'. The section is a section in the object file, or something like `bfd_und_section_ptr' for an undefined symbol or `bfd_com_section_ptr' for a common symbol. If the `_bfd_final_link' routine is also going to need to read the symbol information, the `_bfd_link_add_symbols' routine should save it somewhere attached to the object file BFD. However, the information should only be saved if the `keep_memory' field of the `info' argument is true, so that the `-no-keep-memory' linker switch is effective. The a.out function which adds symbols from an object file is `aout_link_add_object_symbols', and most of the interesting work is in `aout_link_add_symbols'. The latter saves pointers to the hash tables entries created by `_bfd_generic_link_add_one_symbol' indexed by symbol number, so that the `_bfd_final_link' routine does not have to call the hash table lookup routine to locate the entry.  File: bfd.info, Node: Adding symbols from an archive, Prev: Adding symbols from an object file, Up: Adding Symbols to the Hash Table Adding symbols from an archive .............................. When the `_bfd_link_add_symbols' routine is passed an archive, it must look through the symbols defined by the archive and decide which elements of the archive should be included in the link. For each such element it must call the `add_archive_element' linker callback, and it must add the symbols from the object file to the linker hash table. In most cases the work of looking through the symbols in the archive should be done by the `_bfd_generic_link_add_archive_symbols' function. This function builds a hash table from the archive symbol table and looks through the list of undefined symbols to see which elements should be included. `_bfd_generic_link_add_archive_symbols' is passed a function to call to make the final decision about adding an archive element to the link and to do the actual work of adding the symbols to the linker hash table. The function passed to `_bfd_generic_link_add_archive_symbols' must read the symbols of the archive element and decide whether the archive element should be included in the link. If the element is to be included, the `add_archive_element' linker callback routine must be called with the element as an argument, and the elements symbols must be added to the linker hash table just as though the element had itself been passed to the `_bfd_link_add_symbols' function. When the a.out `_bfd_link_add_symbols' function receives an archive, it calls `_bfd_generic_link_add_archive_symbols' passing `aout_link_check_archive_element' as the function argument. `aout_link_check_archive_element' calls `aout_link_check_ar_symbols'. If the latter decides to add the element (an element is only added if it provides a real, non-common, definition for a previously undefined or common symbol) it calls the `add_archive_element' callback and then `aout_link_check_archive_element' calls `aout_link_add_symbols' to actually add the symbols to the linker hash table. The ECOFF back end is unusual in that it does not normally call `_bfd_generic_link_add_archive_symbols', because ECOFF archives already contain a hash table of symbols. The ECOFF back end searches the archive itself to avoid the overhead of creating a new hash table.  File: bfd.info, Node: Performing the Final Link, Prev: Adding Symbols to the Hash Table, Up: Linker Functions Performing the final link ------------------------- When all the input files have been processed, the linker calls the `_bfd_final_link' entry point of the output BFD. This routine is responsible for producing the final output file, which has several aspects. It must relocate the contents of the input sections and copy the data into the output sections. It must build an output symbol table including any local symbols from the input files and the global symbols from the hash table. When producing relocateable output, it must modify the input relocs and write them into the output file. There may also be object format dependent work to be done. The linker will also call the `write_object_contents' entry point when the BFD is closed. The two entry points must work together in order to produce the correct output file. The details of how this works are inevitably dependent upon the specific object file format. The a.out `_bfd_final_link' routine is `NAME(aout,final_link)'. * Menu: * Information provided by the linker:: * Relocating the section contents:: * Writing the symbol table::  File: bfd.info, Node: Information provided by the linker, Next: Relocating the section contents, Prev: Performing the Final Link, Up: Performing the Final Link Information provided by the linker .................................. Before the linker calls the `_bfd_final_link' entry point, it sets up some data structures for the function to use. The `input_bfds' field of the `bfd_link_info' structure will point to a list of all the input files included in the link. These files are linked through the `link_next' field of the `bfd' structure. Each section in the output file will have a list of `link_order' structures attached to the `link_order_head' field (the `link_order' structure is defined in `bfdlink.h'). These structures describe how to create the contents of the output section in terms of the contents of various input sections, fill constants, and, eventually, other types of information. They also describe relocs that must be created by the BFD backend, but do not correspond to any input file; this is used to support -Ur, which builds constructors while generating a relocateable object file.  File: bfd.info, Node: Relocating the section contents, Next: Writing the symbol table, Prev: Information provided by the linker, Up: Performing the Final Link Relocating the section contents ............................... The `_bfd_final_link' function should look through the `link_order' structures attached to each section of the output file. Each `link_order' structure should either be handled specially, or it should be passed to the function `_bfd_default_link_order' which will do the right thing (`_bfd_default_link_order' is defined in `linker.c'). For efficiency, a `link_order' of type `bfd_indirect_link_order' whose associated section belongs to a BFD of the same format as the output BFD must be handled specially. This type of `link_order' describes part of an output section in terms of a section belonging to one of the input files. The `_bfd_final_link' function should read the contents of the section and any associated relocs, apply the relocs to the section contents, and write out the modified section contents. If performing a relocateable link, the relocs themselves must also be modified and written out. The functions `_bfd_relocate_contents' and `_bfd_final_link_relocate' provide some general support for performing the actual relocations, notably overflow checking. Their arguments include information about the symbol the relocation is against and a `reloc_howto_type' argument which describes the relocation to perform. These functions are defined in `reloc.c'. The a.out function which handles reading, relocating, and writing section contents is `aout_link_input_section'. The actual relocation is done in `aout_link_input_section_std' and `aout_link_input_section_ext'.  File: bfd.info, Node: Writing the symbol table, Prev: Relocating the section contents, Up: Performing the Final Link Writing the symbol table ........................ The `_bfd_final_link' function must gather all the symbols in the input files and write them out. It must also write out all the symbols in the global hash table. This must be controlled by the `strip' and `discard' fields of the `bfd_link_info' structure. The local symbols of the input files will not have been entered into the linker hash table. The `_bfd_final_link' routine must consider each input file and include the symbols in the output file. It may be convenient to do this when looking through the `link_order' structures, or it may be done by stepping through the `input_bfds' list. The `_bfd_final_link' routine must also traverse the global hash table to gather all the externally visible symbols. It is possible that most of the externally visible symbols may be written out when considering the symbols of each input file, but it is still necessary to traverse the hash table since the linker script may have defined some symbols that are not in any of the input files. The `strip' field of the `bfd_link_info' structure controls which symbols are written out. The possible values are listed in `bfdlink.h'. If the value is `strip_some', then the `keep_hash' field of the `bfd_link_info' structure is a hash table of symbols to keep; each symbol should be looked up in this hash table, and only symbols which are present should be included in the output file. If the `strip' field of the `bfd_link_info' structure permits local symbols to be written out, the `discard' field is used to further controls which local symbols are included in the output file. If the value is `discard_l', then all local symbols which begin with a certain prefix are discarded; this is controlled by the `bfd_is_local_label_name' entry point. The a.out backend handles symbols by calling `aout_link_write_symbols' on each input BFD and then traversing the global hash table with the function `aout_link_write_other_symbol'. It builds a string table while writing out the symbols, which is written to the output file at the end of `NAME(aout,final_link)'. `bfd_link_split_section' ........................ *Synopsis* boolean bfd_link_split_section(bfd *abfd, asection *sec); *Description* Return nonzero if SEC should be split during a reloceatable or final link. #define bfd_link_split_section(abfd, sec) \ BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))  File: bfd.info, Node: Hash Tables, Prev: Linker Functions, Up: BFD front end Hash Tables =========== BFD provides a simple set of hash table functions. Routines are provided to initialize a hash table, to free a hash table, to look up a string in a hash table and optionally create an entry for it, and to traverse a hash table. There is currently no routine to delete an string from a hash table. The basic hash table does not permit any data to be stored with a string. However, a hash table is designed to present a base class from which other types of hash tables may be derived. These derived types may store additional information with the string. Hash tables were implemented in this way, rather than simply providing a data pointer in a hash table entry, because they were designed for use by the linker back ends. The linker may create thousands of hash table entries, and the overhead of allocating private data and storing and following pointers becomes noticeable. The basic hash table code is in `hash.c'. * Menu: * Creating and Freeing a Hash Table:: * Looking Up or Entering a String:: * Traversing a Hash Table:: * Deriving a New Hash Table Type::  File: bfd.info, Node: Creating and Freeing a Hash Table, Next: Looking Up or Entering a String, Prev: Hash Tables, Up: Hash Tables Creating and freeing a hash table --------------------------------- To create a hash table, create an instance of a `struct bfd_hash_table' (defined in `bfd.h') and call `bfd_hash_table_init' (if you know approximately how many entries you will need, the function `bfd_hash_table_init_n', which takes a SIZE argument, may be used). `bfd_hash_table_init' returns `false' if some sort of error occurs. The function `bfd_hash_table_init' take as an argument a function to use to create new entries. For a basic hash table, use the function `bfd_hash_newfunc'. *Note Deriving a New Hash Table Type:: for why you would want to use a different value for this argument. `bfd_hash_table_init' will create an objalloc which will be used to allocate new entries. You may allocate memory on this objalloc using `bfd_hash_allocate'. Use `bfd_hash_table_free' to free up all the memory that has been allocated for a hash table. This will not free up the `struct bfd_hash_table' itself, which you must provide.  File: bfd.info, Node: Looking Up or Entering a String, Next: Traversing a Hash Table, Prev: Creating and Freeing a Hash Table, Up: Hash Tables Looking up or entering a string ------------------------------- The function `bfd_hash_lookup' is used both to look up a string in the hash table and to create a new entry. If the CREATE argument is `false', `bfd_hash_lookup' will look up a string. If the string is found, it will returns a pointer to a `struct bfd_hash_entry'. If the string is not found in the table `bfd_hash_lookup' will return `NULL'. You should not modify any of the fields in the returns `struct bfd_hash_entry'. If the CREATE argument is `true', the string will be entered into the hash table if it is not already there. Either way a pointer to a `struct bfd_hash_entry' will be returned, either to the existing structure or to a newly created one. In this case, a `NULL' return means that an error occurred. If the CREATE argument is `true', and a new entry is created, the COPY argument is used to decide whether to copy the string onto the hash table objalloc or not. If COPY is passed as `false', you must be careful not to deallocate or modify the string as long as the hash table exists.  File: bfd.info, Node: Traversing a Hash Table, Next: Deriving a New Hash Table Type, Prev: Looking Up or Entering a String, Up: Hash Tables Traversing a hash table ----------------------- The function `bfd_hash_traverse' may be used to traverse a hash table, calling a function on each element. The traversal is done in a random order. `bfd_hash_traverse' takes as arguments a function and a generic `void *' pointer. The function is called with a hash table entry (a `struct bfd_hash_entry *') and the generic pointer passed to `bfd_hash_traverse'. The function must return a `boolean' value, which indicates whether to continue traversing the hash table. If the function returns `false', `bfd_hash_traverse' will stop the traversal and return immediately.  File: bfd.info, Node: Deriving a New Hash Table Type, Prev: Traversing a Hash Table, Up: Hash Tables Deriving a new hash table type ------------------------------ Many uses of hash tables want to store additional information which each entry in the hash table. Some also find it convenient to store additional information with the hash table itself. This may be done using a derived hash table. Since C is not an object oriented language, creating a derived hash table requires sticking together some boilerplate routines with a few differences specific to the type of hash table you want to create. An example of a derived hash table is the linker hash table. The structures for this are defined in `bfdlink.h'. The functions are in `linker.c'. You may also derive a hash table from an already derived hash table. For example, the a.out linker backend code uses a hash table derived from the linker hash table. * Menu: * Define the Derived Structures:: * Write the Derived Creation Routine:: * Write Other Derived Routines::  File: bfd.info, Node: Define the Derived Structures, Next: Write the Derived Creation Routine, Prev: Deriving a New Hash Table Type, Up: Deriving a New Hash Table Type Define the derived structures ............................. You must define a structure for an entry in the hash table, and a structure for the hash table itself. The first field in the structure for an entry in the hash table must be of the type used for an entry in the hash table you are deriving from. If you are deriving from a basic hash table this is `struct bfd_hash_entry', which is defined in `bfd.h'. The first field in the structure for the hash table itself must be of the type of the hash table you are deriving from itself. If you are deriving from a basic hash table, this is `struct bfd_hash_table'. For example, the linker hash table defines `struct bfd_link_hash_entry' (in `bfdlink.h'). The first field, `root', is of type `struct bfd_hash_entry'. Similarly, the first field in `struct bfd_link_hash_table', `table', is of type `struct bfd_hash_table'.  File: bfd.info, Node: Write the Derived Creation Routine, Next: Write Other Derived Routines, Prev: Define the Derived Structures, Up: Deriving a New Hash Table Type Write the derived creation routine .................................. You must write a routine which will create and initialize an entry in the hash table. This routine is passed as the function argument to `bfd_hash_table_init'. In order to permit other hash tables to be derived from the hash table you are creating, this routine must be written in a standard way. The first argument to the creation routine is a pointer to a hash table entry. This may be `NULL', in which case the routine should allocate the right amount of space. Otherwise the space has already been allocated by a hash table type derived from this one. After allocating space, the creation routine must call the creation routine of the hash table type it is derived from, passing in a pointer to the space it just allocated. This will initialize any fields used by the base hash table. Finally the creation routine must initialize any local fields for the new hash table type. Here is a boilerplate example of a creation routine. FUNCTION_NAME is the name of the routine. ENTRY_TYPE is the type of an entry in the hash table you are creating. BASE_NEWFUNC is the name of the creation routine of the hash table type your hash table is derived from. .struct bfd_hash_entry * FUNCTION_NAME (entry, table, string) struct bfd_hash_entry *entry; struct bfd_hash_table *table; const char *string; { struct ENTRY_TYPE *ret = (ENTRY_TYPE *) entry; /* Allocate the structure if it has not already been allocated by a derived class. */ if (ret == (ENTRY_TYPE *) NULL) { ret = ((ENTRY_TYPE *) bfd_hash_allocate (table, sizeof (ENTRY_TYPE))); if (ret == (ENTRY_TYPE *) NULL) return NULL; } /* Call the allocation method of the base class. */ ret = ((ENTRY_TYPE *) BASE_NEWFUNC ((struct bfd_hash_entry *) ret, table, string)); /* Initialize the local fields here. */ return (struct bfd_hash_entry *) ret; } *Description* The creation routine for the linker hash table, which is in `linker.c', looks just like this example. FUNCTION_NAME is `_bfd_link_hash_newfunc'. ENTRY_TYPE is `struct bfd_link_hash_entry'. BASE_NEWFUNC is `bfd_hash_newfunc', the creation routine for a basic hash table. `_bfd_link_hash_newfunc' also initializes the local fields in a linker hash table entry: `type', `written' and `next'.  File: bfd.info, Node: Write Other Derived Routines, Prev: Write the Derived Creation Routine, Up: Deriving a New Hash Table Type Write other derived routines ............................ You will want to write other routines for your new hash table, as well. You will want an initialization routine which calls the initialization routine of the hash table you are deriving from and initializes any other local fields. For the linker hash table, this is `_bfd_link_hash_table_init' in `linker.c'. You will want a lookup routine which calls the lookup routine of the hash table you are deriving from and casts the result. The linker hash table uses `bfd_link_hash_lookup' in `linker.c' (this actually takes an additional argument which it uses to decide how to return the looked up value). You may want a traversal routine. This should just call the traversal routine of the hash table you are deriving from with appropriate casts. The linker hash table uses `bfd_link_hash_traverse' in `linker.c'. These routines may simply be defined as macros. For example, the a.out backend linker hash table, which is derived from the linker hash table, uses macros for the lookup and traversal routines. These are `aout_link_hash_lookup' and `aout_link_hash_traverse' in aoutx.h.  File: bfd.info, Node: BFD back ends, Next: Index, Prev: BFD front end, Up: Top BFD back ends ************* * Menu: * What to Put Where:: * aout :: a.out backends * coff :: coff backends * elf :: elf backends  File: bfd.info, Node: What to Put Where, Next: aout, Prev: BFD back ends, Up: BFD back ends All of BFD lives in one directory.  File: bfd.info, Node: aout, Next: coff, Prev: What to Put Where, Up: BFD back ends a.out backends ============== *Description* BFD supports a number of different flavours of a.out format, though the major differences are only the sizes of the structures on disk, and the shape of the relocation information. The support is split into a basic support file `aoutx.h' and other files which derive functions from the base. One derivation file is `aoutf1.h' (for a.out flavour 1), and adds to the basic a.out functions support for sun3, sun4, 386 and 29k a.out files, to create a target jump vector for a specific target. This information is further split out into more specific files for each machine, including `sunos.c' for sun3 and sun4, `newsos3.c' for the Sony NEWS, and `demo64.c' for a demonstration of a 64 bit a.out format. The base file `aoutx.h' defines general mechanisms for reading and writing records to and from disk and various other methods which BFD requires. It is included by `aout32.c' and `aout64.c' to form the names `aout_32_swap_exec_header_in', `aout_64_swap_exec_header_in', etc. As an example, this is what goes on to make the back end for a sun4, from `aout32.c': #define ARCH_SIZE 32 #include "aoutx.h" Which exports names: ... aout_32_canonicalize_reloc aout_32_find_nearest_line aout_32_get_lineno aout_32_get_reloc_upper_bound ... from `sunos.c': #define TARGET_NAME "a.out-sunos-big" #define VECNAME sunos_big_vec #include "aoutf1.h" requires all the names from `aout32.c', and produces the jump vector sunos_big_vec The file `host-aout.c' is a special case. It is for a large set of hosts that use "more or less standard" a.out files, and for which cross-debugging is not interesting. It uses the standard 32-bit a.out support routines, but determines the file offsets and addresses of the text, data, and BSS sections, the machine architecture and machine type, and the entry point address, in a host-dependent manner. Once these values have been determined, generic code is used to handle the object file. When porting it to run on a new system, you must supply: HOST_PAGE_SIZE HOST_SEGMENT_SIZE HOST_MACHINE_ARCH (optional) HOST_MACHINE_MACHINE (optional) HOST_TEXT_START_ADDR HOST_STACK_END_ADDR in the file `../include/sys/h-XXX.h' (for your host). These values, plus the structures and macros defined in `a.out.h' on your host system, will produce a BFD target that will access ordinary a.out files on your host. To configure a new machine to use `host-aout.c', specify: TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec TDEPFILES= host-aout.o trad-core.o in the `config/XXX.mt' file, and modify `configure.in' to use the `XXX.mt' file (by setting "`bfd_target=XXX'") when your configuration is selected. Relocations ----------- *Description* The file `aoutx.h' provides for both the *standard* and *extended* forms of a.out relocation records. The standard records contain only an address, a symbol index, and a type field. The extended records (used on 29ks and sparcs) also have a full integer for an addend. Internal entry points --------------------- *Description* `aoutx.h' exports several routines for accessing the contents of an a.out file, which are gathered and exported in turn by various format specific files (eg sunos.c). `aout_SIZE_swap_exec_header_in' ............................... *Synopsis* void aout_SIZE_swap_exec_header_in, (bfd *abfd, struct external_exec *raw_bytes, struct internal_exec *execp); *Description* Swap the information in an executable header RAW_BYTES taken from a raw byte stream memory image into the internal exec header structure EXECP. `aout_SIZE_swap_exec_header_out' ................................ *Synopsis* void aout_SIZE_swap_exec_header_out (bfd *abfd, struct internal_exec *execp, struct external_exec *raw_bytes); *Description* Swap the information in an internal exec header structure EXECP into the buffer RAW_BYTES ready for writing to disk. `aout_SIZE_some_aout_object_p' .............................. *Synopsis* const bfd_target *aout_SIZE_some_aout_object_p (bfd *abfd, const bfd_target *(*callback_to_real_object_p)()); *Description* Some a.out variant thinks that the file open in ABFD checking is an a.out file. Do some more checking, and set up for access if it really is. Call back to the calling environment's "finish up" function just before returning, to handle any last-minute setup. `aout_SIZE_mkobject' .................... *Synopsis* boolean aout_SIZE_mkobject, (bfd *abfd); *Description* Initialize BFD ABFD for use with a.out files. `aout_SIZE_machine_type' ........................ *Synopsis* enum machine_type aout_SIZE_machine_type (enum bfd_architecture arch, unsigned long machine)); *Description* Keep track of machine architecture and machine type for a.out's. Return the `machine_type' for a particular architecture and machine, or `M_UNKNOWN' if that exact architecture and machine can't be represented in a.out format. If the architecture is understood, machine type 0 (default) is always understood. `aout_SIZE_set_arch_mach' ......................... *Synopsis* boolean aout_SIZE_set_arch_mach, (bfd *, enum bfd_architecture arch, unsigned long machine)); *Description* Set the architecture and the machine of the BFD ABFD to the values ARCH and MACHINE. Verify that ABFD's format can support the architecture required. `aout_SIZE_new_section_hook' ............................ *Synopsis* boolean aout_SIZE_new_section_hook, (bfd *abfd, asection *newsect)); *Description* Called by the BFD in response to a `bfd_make_section' request.