Subversion Repositories or1k

This is bfd.info, produced by makeinfo version 4.0 from bfd.texinfo.

START-INFO-DIR-ENTRY

* Bfd: (bfd).                   The Binary File Descriptor library.

END-INFO-DIR-ENTRY

   This file documents the BFD library.

   Copyright (C) 1991, 2000 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document

     under the terms of the GNU Free Documentation License, Version 1.1

     or any later version published by the Free Software Foundation;

   with no Invariant Sections, with no Front-Cover Texts, and with no

    Back-Cover Texts.  A copy of the license is included in the

section entitled "GNU Free Documentation License".

File: bfd.info,  Node: 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: GNU Free Documentation License,  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.