Ignore:
Timestamp:
Aug 16, 2003, 6:59:22 PM (22 years ago)
Author:
bird
Message:

binutils v2.14 - offical sources.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • branches/GNU/src/binutils/bfd/doc/bfd.info-5

    • Property cvs2svn:cvs-rev changed from 1.1 to 1.1.1.2
    r608 r609  
    1 This is bfd.info, produced by makeinfo version 4.0 from bfd.texinfo.
     1This is bfd.info, produced by makeinfo version 4. from bfd.texinfo.
    22
    33START-INFO-DIR-ENTRY
    … …  
    77   This file documents the BFD library.
    88
    9    Copyright (C) 1991, 2000 Free Software Foundation, Inc.
     9   Copyright (C) 1991, 2000 Free Software Foundation, Inc.
    1010
    1111   Permission is granted to copy, distribute and/or modify this document
    … …  
    1717
    1818
    19 File: bfd.info,  Node: Linker Functions,  Next: Hash Tables,  Prev: File Caching,  Up: BFD front end
    20 
    21 Linker Functions
    22 ================
    23 
    24    The linker uses three special entry points in the BFD target vector.
    25 It is not necessary to write special routines for these entry points
    26 when creating a new BFD back end, since generic versions are provided.
    27 However, writing them can speed up linking and make it use
    28 significantly less runtime memory.
    29 
    30    The first routine creates a hash table used by the other routines.
    31 The second routine adds the symbols from an object file to the hash
    32 table.  The third routine takes all the object files and links them
    33 together to create the output file.  These routines are designed so
    34 that the linker proper does not need to know anything about the symbols
    35 in the object files that it is linking.  The linker merely arranges the
    36 sections as directed by the linker script and lets BFD handle the
    37 details of symbols and relocs.
    38 
    39    The second routine and third routines are passed a pointer to a
    40 `struct bfd_link_info' structure (defined in `bfdlink.h') which holds
    41 information relevant to the link, including the linker hash table
    42 (which was created by the first routine) and a set of callback
    43 functions to the linker proper.
    44 
    45    The generic linker routines are in `linker.c', and use the header
    46 file `genlink.h'.  As of this writing, the only back ends which have
    47 implemented versions of these routines are a.out (in `aoutx.h') and
    48 ECOFF (in `ecoff.c').  The a.out routines are used as examples
    49 throughout this section.
    50 
    51 * Menu:
    52 
    53 * Creating a Linker Hash Table::
    54 * Adding Symbols to the Hash Table::
    55 * Performing the Final Link::
     19File: bfd.info,  Node: bfd_target,  Prev: Targets,  Up: Targets
     20
     21bfd_target
     22----------
     23
     24   *Description*
     25This structure contains everything that BFD knows about a target. It
     26includes things like its byte order, name, and which routines to call
     27to do various operations.
     28
     29   Every BFD points to a target structure with its `xvec' member.
     30
     31   The macros below are used to dispatch to functions through the
     32`bfd_target' vector. They are used in a number of macros further down
     33in `bfd.h', and are also used when calling various routines by hand
     34inside the BFD implementation.  The ARGLIST argument must be
     35parenthesized; it contains all the arguments to the called function.
     36
     37   They make the documentation (more) unpleasant to read, so if someone
     38wants to fix this and not break the above, please do.
     39     #define BFD_SEND(bfd, message, arglist) \
     40                    ((*((bfd)->xvec->message)) arglist)
     41     
     42     #ifdef DEBUG_BFD_SEND
     43     #undef BFD_SEND
     44     #define BFD_SEND(bfd, message, arglist) \
     45       (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
     46         ((*((bfd)->xvec->message)) arglist) : \
     47         (bfd_assert (__FILE__,__LINE__), NULL))
     48     #endif
     49   For operations which index on the BFD format:
     50     #define BFD_SEND_FMT(bfd, message, arglist) \
     51                 (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist)
     52     
     53     #ifdef DEBUG_BFD_SEND
     54     #undef BFD_SEND_FMT
     55     #define BFD_SEND_FMT(bfd, message, arglist) \
     56       (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \
     57        (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \
     58        (bfd_assert (__FILE__,__LINE__), NULL))
     59     #endif
     60   This is the structure which defines the type of BFD this is.  The
     61`xvec' member of the struct `bfd' itself points here.  Each module that
     62implements access to a different target under BFD, defines one of these.
     63
     64   FIXME, these names should be rationalised with the names of the
     65entry points which call them. Too bad we can't have one macro to define
     66them both!
     67     enum bfd_flavour
     68     {
     69       bfd_target_unknown_flavour,
     70       bfd_target_aout_flavour,
     71       bfd_target_coff_flavour,
     72       bfd_target_ecoff_flavour,
     73       bfd_target_xcoff_flavour,
     74       bfd_target_elf_flavour,
     75       bfd_target_ieee_flavour,
     76       bfd_target_nlm_flavour,
     77       bfd_target_oasys_flavour,
     78       bfd_target_tekhex_flavour,
     79       bfd_target_srec_flavour,
     80       bfd_target_ihex_flavour,
     81       bfd_target_som_flavour,
     82       bfd_target_os9k_flavour,
     83       bfd_target_versados_flavour,
     84       bfd_target_msdos_flavour,
     85       bfd_target_ovax_flavour,
     86       bfd_target_evax_flavour,
     87       bfd_target_mmo_flavour,
     88       bfd_target_mach_o_flavour,
     89       bfd_target_pef_flavour,
     90       bfd_target_pef_xlib_flavour,
     91       bfd_target_sym_flavour
     92     };
     93     
     94     enum bfd_endian { BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN };
     95     
     96     /* Forward declaration.  */
     97     typedef struct bfd_link_info _bfd_link_info;
     98     
     99     typedef struct bfd_target
     100     {
     101       /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc.  */
     102       char *name;
     103     
     104      /* The "flavour" of a back end is a general indication about
     105         the contents of a file.  */
     106       enum bfd_flavour flavour;
     107     
     108       /* The order of bytes within the data area of a file.  */
     109       enum bfd_endian byteorder;
     110     
     111      /* The order of bytes within the header parts of a file.  */
     112       enum bfd_endian header_byteorder;
     113     
     114       /* A mask of all the flags which an executable may have set -
     115          from the set `BFD_NO_FLAGS', `HAS_RELOC', ...`D_PAGED'.  */
     116       flagword object_flags;
     117     
     118      /* A mask of all the flags which a section may have set - from
     119         the set `SEC_NO_FLAGS', `SEC_ALLOC', ...`SET_NEVER_LOAD'.  */
     120       flagword section_flags;
     121     
     122      /* The character normally found at the front of a symbol.
     123         (if any), perhaps `_'.  */
     124       char symbol_leading_char;
     125     
     126      /* The pad character for file names within an archive header.  */
     127       char ar_pad_char;
     128     
     129       /* The maximum number of characters in an archive header.  */
     130       unsigned short ar_max_namelen;
     131     
     132       /* Entries for byte swapping for data. These are different from the
     133          other entry points, since they don't take a BFD asthe first argument.
     134          Certain other handlers could do the same.  */
     135       bfd_vma        (*bfd_getx64) PARAMS ((const bfd_byte *));
     136       bfd_signed_vma (*bfd_getx_signed_64) PARAMS ((const bfd_byte *));
     137       void           (*bfd_putx64) PARAMS ((bfd_vma, bfd_byte *));
     138       bfd_vma        (*bfd_getx32) PARAMS ((const bfd_byte *));
     139       bfd_signed_vma (*bfd_getx_signed_32) PARAMS ((const bfd_byte *));
     140       void           (*bfd_putx32) PARAMS ((bfd_vma, bfd_byte *));
     141       bfd_vma        (*bfd_getx16) PARAMS ((const bfd_byte *));
     142       bfd_signed_vma (*bfd_getx_signed_16) PARAMS ((const bfd_byte *));
     143       void           (*bfd_putx16) PARAMS ((bfd_vma, bfd_byte *));
     144     
     145       /* Byte swapping for the headers.  */
     146       bfd_vma        (*bfd_h_getx64) PARAMS ((const bfd_byte *));
     147       bfd_signed_vma (*bfd_h_getx_signed_64) PARAMS ((const bfd_byte *));
     148       void           (*bfd_h_putx64) PARAMS ((bfd_vma, bfd_byte *));
     149       bfd_vma        (*bfd_h_getx32) PARAMS ((const bfd_byte *));
     150       bfd_signed_vma (*bfd_h_getx_signed_32) PARAMS ((const bfd_byte *));
     151       void           (*bfd_h_putx32) PARAMS ((bfd_vma, bfd_byte *));
     152       bfd_vma        (*bfd_h_getx16) PARAMS ((const bfd_byte *));
     153       bfd_signed_vma (*bfd_h_getx_signed_16) PARAMS ((const bfd_byte *));
     154       void           (*bfd_h_putx16) PARAMS ((bfd_vma, bfd_byte *));
     155     
     156       /* Format dependent routines: these are vectors of entry points
     157          within the target vector structure, one for each format to check.  */
     158     
     159       /* Check the format of a file being read.  Return a `bfd_target *' or zero.  */
     160       const struct bfd_target *(*_bfd_check_format[bfd_type_end]) PARAMS ((bfd *));
     161     
     162       /* Set the format of a file being written.  */
     163       bfd_boolean (*_bfd_set_format[bfd_type_end]) PARAMS ((bfd *));
     164     
     165       /* Write cached information into a file being written, at `bfd_close'.  */
     166       bfd_boolean (*_bfd_write_contents[bfd_type_end]) PARAMS ((bfd *));
     167   The general target vector.  These vectors are initialized using the
     168BFD_JUMP_TABLE macros.
     169
     170       /* Generic entry points.  */
     171   Do not "beautify" the CONCAT* macro args.  Traditional C will not
     172remove whitespace added here, and thus will fail to concatenate the
     173tokens.
     174     #define BFD_JUMP_TABLE_GENERIC(NAME) \
     175     CONCAT2 (NAME,_close_and_cleanup), \
     176     CONCAT2 (NAME,_bfd_free_cached_info), \
     177     CONCAT2 (NAME,_new_section_hook), \
     178     CONCAT2 (NAME,_get_section_contents), \
     179     CONCAT2 (NAME,_get_section_contents_in_window)
     180     
     181       /* Called when the BFD is being closed to do any necessary cleanup.  */
     182       bfd_boolean (*_close_and_cleanup) PARAMS ((bfd *));
     183       /* Ask the BFD to free all cached information.  */
     184       bfd_boolean (*_bfd_free_cached_info) PARAMS ((bfd *));
     185       /* Called when a new section is created.  */
     186       bfd_boolean (*_new_section_hook) PARAMS ((bfd *, sec_ptr));
     187       /* Read the contents of a section.  */
     188       bfd_boolean (*_bfd_get_section_contents)
     189         PARAMS ((bfd *, sec_ptr, PTR, file_ptr, bfd_size_type));
     190       bfd_boolean (*_bfd_get_section_contents_in_window)
     191         PARAMS ((bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type));
     192     
     193       /* Entry points to copy private data.  */
     194     #define BFD_JUMP_TABLE_COPY(NAME) \
     195     CONCAT2 (NAME,_bfd_copy_private_bfd_data), \
     196     CONCAT2 (NAME,_bfd_merge_private_bfd_data), \
     197     CONCAT2 (NAME,_bfd_copy_private_section_data), \
     198     CONCAT2 (NAME,_bfd_copy_private_symbol_data), \
     199     CONCAT2 (NAME,_bfd_set_private_flags), \
     200     CONCAT2 (NAME,_bfd_print_private_bfd_data) \
     201       /* Called to copy BFD general private data from one object file
     202          to another.  */
     203       bfd_boolean (*_bfd_copy_private_bfd_data) PARAMS ((bfd *, bfd *));
     204       /* Called to merge BFD general private data from one object file
     205          to a common output file when linking.  */
     206       bfd_boolean (*_bfd_merge_private_bfd_data) PARAMS ((bfd *, bfd *));
     207       /* Called to copy BFD private section data from one object file
     208          to another.  */
     209       bfd_boolean (*_bfd_copy_private_section_data)
     210         PARAMS ((bfd *, sec_ptr, bfd *, sec_ptr));
     211       /* Called to copy BFD private symbol data from one symbol
     212          to another.  */
     213       bfd_boolean (*_bfd_copy_private_symbol_data)
     214         PARAMS ((bfd *, asymbol *, bfd *, asymbol *));
     215       /* Called to set private backend flags.  */
     216       bfd_boolean (*_bfd_set_private_flags) PARAMS ((bfd *, flagword));
     217     
     218       /* Called to print private BFD data.  */
     219       bfd_boolean (*_bfd_print_private_bfd_data) PARAMS ((bfd *, PTR));
     220     
     221       /* Core file entry points.  */
     222     #define BFD_JUMP_TABLE_CORE(NAME) \
     223     CONCAT2 (NAME,_core_file_failing_command), \
     224     CONCAT2 (NAME,_core_file_failing_signal), \
     225     CONCAT2 (NAME,_core_file_matches_executable_p)
     226       char *      (*_core_file_failing_command) PARAMS ((bfd *));
     227       int         (*_core_file_failing_signal) PARAMS ((bfd *));
     228       bfd_boolean (*_core_file_matches_executable_p) PARAMS ((bfd *, bfd *));
     229     
     230       /* Archive entry points.  */
     231     #define BFD_JUMP_TABLE_ARCHIVE(NAME) \
     232     CONCAT2 (NAME,_slurp_armap), \
     233     CONCAT2 (NAME,_slurp_extended_name_table), \
     234     CONCAT2 (NAME,_construct_extended_name_table), \
     235     CONCAT2 (NAME,_truncate_arname), \
     236     CONCAT2 (NAME,_write_armap), \
     237     CONCAT2 (NAME,_read_ar_hdr), \
     238     CONCAT2 (NAME,_openr_next_archived_file), \
     239     CONCAT2 (NAME,_get_elt_at_index), \
     240     CONCAT2 (NAME,_generic_stat_arch_elt), \
     241     CONCAT2 (NAME,_update_armap_timestamp)
     242       bfd_boolean (*_bfd_slurp_armap) PARAMS ((bfd *));
     243       bfd_boolean (*_bfd_slurp_extended_name_table) PARAMS ((bfd *));
     244       bfd_boolean (*_bfd_construct_extended_name_table)
     245         PARAMS ((bfd *, char **, bfd_size_type *, const char **));
     246       void        (*_bfd_truncate_arname) PARAMS ((bfd *, const char *, char *));
     247       bfd_boolean (*write_armap)
     248         PARAMS ((bfd *, unsigned int, struct orl *, unsigned int, int));
     249       PTR         (*_bfd_read_ar_hdr_fn) PARAMS ((bfd *));
     250       bfd *       (*openr_next_archived_file) PARAMS ((bfd *, bfd *));
     251     #define bfd_get_elt_at_index(b,i) BFD_SEND(b, _bfd_get_elt_at_index, (b,i))
     252       bfd *       (*_bfd_get_elt_at_index) PARAMS ((bfd *, symindex));
     253       int         (*_bfd_stat_arch_elt) PARAMS ((bfd *, struct stat *));
     254       bfd_boolean (*_bfd_update_armap_timestamp) PARAMS ((bfd *));
     255     
     256       /* Entry points used for symbols.  */
     257     #define BFD_JUMP_TABLE_SYMBOLS(NAME) \
     258     CONCAT2 (NAME,_get_symtab_upper_bound), \
     259     CONCAT2 (NAME,_get_symtab), \
     260     CONCAT2 (NAME,_make_empty_symbol), \
     261     CONCAT2 (NAME,_print_symbol), \
     262     CONCAT2 (NAME,_get_symbol_info), \
     263     CONCAT2 (NAME,_bfd_is_local_label_name), \
     264     CONCAT2 (NAME,_get_lineno), \
     265     CONCAT2 (NAME,_find_nearest_line), \
     266     CONCAT2 (NAME,_bfd_make_debug_symbol), \
     267     CONCAT2 (NAME,_read_minisymbols), \
     268     CONCAT2 (NAME,_minisymbol_to_symbol)
     269       long        (*_bfd_get_symtab_upper_bound) PARAMS ((bfd *));
     270       long        (*_bfd_canonicalize_symtab) PARAMS ((bfd *,
     271                                                     struct symbol_cache_entry **));
     272       struct symbol_cache_entry *
     273                   (*_bfd_make_empty_symbol) PARAMS ((bfd *));
     274       void        (*_bfd_print_symbol)
     275         PARAMS ((bfd *, PTR, struct symbol_cache_entry *, bfd_print_symbol_type));
     276     #define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e))
     277       void        (*_bfd_get_symbol_info)
     278         PARAMS ((bfd *, struct symbol_cache_entry *, symbol_info *));
     279     #define bfd_get_symbol_info(b,p,e) BFD_SEND(b, _bfd_get_symbol_info, (b,p,e))
     280       bfd_boolean (*_bfd_is_local_label_name) PARAMS ((bfd *, const char *));
     281     
     282       alent *     (*_get_lineno) PARAMS ((bfd *, struct symbol_cache_entry *));
     283       bfd_boolean (*_bfd_find_nearest_line)
     284         PARAMS ((bfd *, struct sec *, struct symbol_cache_entry **, bfd_vma,
     285                  const char **, const char **, unsigned int *));
     286      /* Back-door to allow format-aware applications to create debug symbols
     287         while using BFD for everything else.  Currently used by the assembler
     288         when creating COFF files.  */
     289       asymbol *   (*_bfd_make_debug_symbol)
     290         PARAMS ((bfd *, void *, unsigned long size));
     291     #define bfd_read_minisymbols(b, d, m, s) \
     292       BFD_SEND (b, _read_minisymbols, (b, d, m, s))
     293       long        (*_read_minisymbols)
     294         PARAMS ((bfd *, bfd_boolean, PTR *, unsigned int *));
     295     #define bfd_minisymbol_to_symbol(b, d, m, f) \
     296       BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f))
     297       asymbol *   (*_minisymbol_to_symbol)
     298         PARAMS ((bfd *, bfd_boolean, const PTR, asymbol *));
     299     
     300       /* Routines for relocs.  */
     301     #define BFD_JUMP_TABLE_RELOCS(NAME) \
     302     CONCAT2 (NAME,_get_reloc_upper_bound), \
     303     CONCAT2 (NAME,_canonicalize_reloc), \
     304     CONCAT2 (NAME,_bfd_reloc_type_lookup)
     305       long        (*_get_reloc_upper_bound) PARAMS ((bfd *, sec_ptr));
     306       long        (*_bfd_canonicalize_reloc)
     307         PARAMS ((bfd *, sec_ptr, arelent **, struct symbol_cache_entry **));
     308       /* See documentation on reloc types.  */
     309       reloc_howto_type *
     310                   (*reloc_type_lookup) PARAMS ((bfd *, bfd_reloc_code_real_type));
     311     
     312       /* Routines used when writing an object file.  */
     313     #define BFD_JUMP_TABLE_WRITE(NAME) \
     314     CONCAT2 (NAME,_set_arch_mach), \
     315     CONCAT2 (NAME,_set_section_contents)
     316       bfd_boolean (*_bfd_set_arch_mach)
     317         PARAMS ((bfd *, enum bfd_architecture, unsigned long));
     318       bfd_boolean (*_bfd_set_section_contents)
     319         PARAMS ((bfd *, sec_ptr, PTR, file_ptr, bfd_size_type));
     320     
     321       /* Routines used by the linker.  */
     322     #define BFD_JUMP_TABLE_LINK(NAME) \
     323     CONCAT2 (NAME,_sizeof_headers), \
     324     CONCAT2 (NAME,_bfd_get_relocated_section_contents), \
     325     CONCAT2 (NAME,_bfd_relax_section), \
     326     CONCAT2 (NAME,_bfd_link_hash_table_create), \
     327     CONCAT2 (NAME,_bfd_link_hash_table_free), \
     328     CONCAT2 (NAME,_bfd_link_add_symbols), \
     329     CONCAT2 (NAME,_bfd_link_just_syms), \
     330     CONCAT2 (NAME,_bfd_final_link), \
     331     CONCAT2 (NAME,_bfd_link_split_section), \
     332     CONCAT2 (NAME,_bfd_gc_sections), \
     333     CONCAT2 (NAME,_bfd_merge_sections), \
     334     CONCAT2 (NAME,_bfd_discard_group)
     335       int         (*_bfd_sizeof_headers) PARAMS ((bfd *, bfd_boolean));
     336       bfd_byte *  (*_bfd_get_relocated_section_contents)
     337         PARAMS ((bfd *, struct bfd_link_info *, struct bfd_link_order *,
     338                  bfd_byte *, bfd_boolean, struct symbol_cache_entry **));
     339     
     340       bfd_boolean (*_bfd_relax_section)
     341         PARAMS ((bfd *, struct sec *, struct bfd_link_info *, bfd_boolean *));
     342     
     343       /* Create a hash table for the linker.  Different backends store
     344          different information in this table.  */
     345       struct bfd_link_hash_table *
     346                   (*_bfd_link_hash_table_create) PARAMS ((bfd *));
     347     
     348       /* Release the memory associated with the linker hash table.  */
     349       void        (*_bfd_link_hash_table_free)
     350         PARAMS ((struct bfd_link_hash_table *));
     351     
     352       /* Add symbols from this object file into the hash table.  */
     353       bfd_boolean (*_bfd_link_add_symbols)
     354         PARAMS ((bfd *, struct bfd_link_info *));
     355     
     356       /* Indicate that we are only retrieving symbol values from this section.  */
     357       void        (*_bfd_link_just_syms)
     358         PARAMS ((asection *, struct bfd_link_info *));
     359     
     360       /* Do a link based on the link_order structures attached to each
     361          section of the BFD.  */
     362       bfd_boolean (*_bfd_final_link) PARAMS ((bfd *, struct bfd_link_info *));
     363     
     364       /* Should this section be split up into smaller pieces during linking.  */
     365       bfd_boolean (*_bfd_link_split_section) PARAMS ((bfd *, struct sec *));
     366     
     367       /* Remove sections that are not referenced from the output.  */
     368       bfd_boolean (*_bfd_gc_sections) PARAMS ((bfd *, struct bfd_link_info *));
     369     
     370       /* Attempt to merge SEC_MERGE sections.  */
     371       bfd_boolean (*_bfd_merge_sections) PARAMS ((bfd *, struct bfd_link_info *));
     372     
     373       /* Discard members of a group.  */
     374       bfd_boolean (*_bfd_discard_group) PARAMS ((bfd *, struct sec *));
     375     
     376       /* Routines to handle dynamic symbols and relocs.  */
     377     #define BFD_JUMP_TABLE_DYNAMIC(NAME) \
     378     CONCAT2 (NAME,_get_dynamic_symtab_upper_bound), \
     379     CONCAT2 (NAME,_canonicalize_dynamic_symtab), \
     380     CONCAT2 (NAME,_get_dynamic_reloc_upper_bound), \
     381     CONCAT2 (NAME,_canonicalize_dynamic_reloc)
     382       /* Get the amount of memory required to hold the dynamic symbols.  */
     383       long        (*_bfd_get_dynamic_symtab_upper_bound) PARAMS ((bfd *));
     384       /* Read in the dynamic symbols.  */
     385       long        (*_bfd_canonicalize_dynamic_symtab)
     386         PARAMS ((bfd *, struct symbol_cache_entry **));
     387       /* Get the amount of memory required to hold the dynamic relocs.  */
     388       long        (*_bfd_get_dynamic_reloc_upper_bound) PARAMS ((bfd *));
     389       /* Read in the dynamic relocs.  */
     390       long        (*_bfd_canonicalize_dynamic_reloc)
     391         PARAMS ((bfd *, arelent **, struct symbol_cache_entry **));
     392   A pointer to an alternative bfd_target in case the current one is not
     393satisfactory.  This can happen when the target cpu supports both big
     394and little endian code, and target chosen by the linker has the wrong
     395endianness.  The function open_output() in ld/ldlang.c uses this field
     396to find an alternative output format that is suitable.
     397       /* Opposite endian version of this target.  */
     398       const struct bfd_target * alternative_target;
     399     
     400       /* Data for use by back-end routines, which isn't
     401          generic enough to belong in this structure.  */
     402       PTR backend_data;
     403     
     404     } bfd_target;
     405
     406`bfd_set_default_target'
     407........................
     408
     409   *Synopsis*
     410     bfd_boolean bfd_set_default_target (const char *name);
     411   *Description*
     412Set the default target vector to use when recognizing a BFD.  This
     413takes the name of the target, which may be a BFD target name or a
     414configuration triplet.
     415
     416`bfd_find_target'
     417.................
     418
     419   *Synopsis*
     420     const bfd_target *bfd_find_target (const char *target_name, bfd *abfd);
     421   *Description*
     422Return a pointer to the transfer vector for the object target named
     423TARGET_NAME.  If TARGET_NAME is `NULL', choose the one in the
     424environment variable `GNUTARGET'; if that is null or not defined, then
     425choose the first entry in the target list.  Passing in the string
     426"default" or setting the environment variable to "default" will cause
     427the first entry in the target list to be returned, and
     428"target_defaulted" will be set in the BFD.  This causes
     429`bfd_check_format' to loop over all the targets to find the one that
     430matches the file being read.
     431
     432`bfd_target_list'
     433.................
     434
     435   *Synopsis*
     436     const char ** bfd_target_list (void);
     437   *Description*
     438Return a freshly malloced NULL-terminated vector of the names of all
     439the valid BFD targets. Do not modify the names.
     440
     441`bfd_seach_for_target'
     442......................
     443
     444   *Synopsis*
     445     const bfd_target * bfd_search_for_target (int (* search_func)
     446            (const bfd_target *, void *),
     447         void *);
     448   *Description*
     449Return a pointer to the first transfer vector in the list of transfer
     450vectors maintained by BFD that produces a non-zero result when passed
     451to the function SEARCH_FUNC.  The parameter DATA is passed, unexamined,
     452to the search function.
    56453
    57454
    58 File: bfd.info,  Node: Creating a Linker Hash Table,  Next: Adding Symbols to the Hash Table,  Prev: Linker Functions,  Up: Linker Functions
    59 
    60 Creating a linker hash table
    61 ----------------------------
    62 
    63    The linker routines must create a hash table, which must be derived
    64 from `struct bfd_link_hash_table' described in `bfdlink.c'.  *Note Hash
    65 Tables::, for information on how to create a derived hash table.  This
    66 entry point is called using the target vector of the linker output file.
    67 
    68    The `_bfd_link_hash_table_create' entry point must allocate and
    69 initialize an instance of the desired hash table.  If the back end does
    70 not require any additional information to be stored with the entries in
    71 the hash table, the entry point may simply create a `struct
    72 bfd_link_hash_table'.  Most likely, however, some additional
    73 information will be needed.
    74 
    75    For example, with each entry in the hash table the a.out linker
    76 keeps the index the symbol has in the final output file (this index
    77 number is used so that when doing a relocateable link the symbol index
    78 used in the output file can be quickly filled in when copying over a
    79 reloc).  The a.out linker code defines the required structures and
    80 functions for a hash table derived from `struct bfd_link_hash_table'.
    81 The a.out linker hash table is created by the function
    82 `NAME(aout,link_hash_table_create)'; it simply allocates space for the
    83 hash table, initializes it, and returns a pointer to it.
    84 
    85    When writing the linker routines for a new back end, you will
    86 generally not know exactly which fields will be required until you have
    87 finished.  You should simply create a new hash table which defines no
    88 additional fields, and then simply add fields as they become necessary.
     455File: bfd.info,  Node: Architectures,  Next: Opening and Closing,  Prev: Targets,  Up: BFD front end
     456
     457Architectures
     458=============
     459
     460   BFD keeps one atom in a BFD describing the architecture of the data
     461attached to the BFD: a pointer to a `bfd_arch_info_type'.
     462
     463   Pointers to structures can be requested independently of a BFD so
     464that an architecture's information can be interrogated without access
     465to an open BFD.
     466
     467   The architecture information is provided by each architecture
     468package.  The set of default architectures is selected by the macro
     469`SELECT_ARCHITECTURES'.  This is normally set up in the
     470`config/TARGET.mt' file of your choice.  If the name is not defined,
     471then all the architectures supported are included.
     472
     473   When BFD starts up, all the architectures are called with an
     474initialize method.  It is up to the architecture back end to insert as
     475many items into the list of architectures as it wants to; generally
     476this would be one for each machine and one for the default case (an
     477item with a machine field of 0).
     478
     479   BFD's idea of an architecture is implemented in `archures.c'.
     480
     481bfd_architecture
     482----------------
     483
     484   *Description*
     485This enum gives the object file's CPU architecture, in a global
     486sense--i.e., what processor family does it belong to?  Another field
     487indicates which processor within the family is in use.  The machine
     488gives a number which distinguishes different versions of the
     489architecture, containing, for example, 2 and 3 for Intel i960 KA and
     490i960 KB, and 68020 and 68030 for Motorola 68020 and 68030.
     491     enum bfd_architecture
     492     {
     493       bfd_arch_unknown,   /* File arch not known.  */
     494       bfd_arch_obscure,   /* Arch known, not one of these.  */
     495       bfd_arch_m68k,      /* Motorola 68xxx */
     496     #define bfd_mach_m68000 1
     497     #define bfd_mach_m68008 2
     498     #define bfd_mach_m68010 3
     499     #define bfd_mach_m68020 4
     500     #define bfd_mach_m68030 5
     501     #define bfd_mach_m68040 6
     502     #define bfd_mach_m68060 7
     503     #define bfd_mach_cpu32  8
     504     #define bfd_mach_mcf5200  9
     505     #define bfd_mach_mcf5206e 10
     506     #define bfd_mach_mcf5307  11
     507     #define bfd_mach_mcf5407  12
     508       bfd_arch_vax,       /* DEC Vax */
     509       bfd_arch_i960,      /* Intel 960 */
     510         /* The order of the following is important.
     511            lower number indicates a machine type that
     512            only accepts a subset of the instructions
     513            available to machines with higher numbers.
     514            The exception is the "ca", which is
     515            incompatible with all other machines except
     516            "core".  */
     517     
     518     #define bfd_mach_i960_core      1
     519     #define bfd_mach_i960_ka_sa     2
     520     #define bfd_mach_i960_kb_sb     3
     521     #define bfd_mach_i960_mc        4
     522     #define bfd_mach_i960_xa        5
     523     #define bfd_mach_i960_ca        6
     524     #define bfd_mach_i960_jx        7
     525     #define bfd_mach_i960_hx        8
     526     
     527       bfd_arch_or32,      /* OpenRISC 32 */
     528     
     529       bfd_arch_a29k,      /* AMD 29000 */
     530       bfd_arch_sparc,     /* SPARC */
     531     #define bfd_mach_sparc                 1
     532     /* The difference between v8plus and v9 is that v9 is a true 64 bit env.  */
     533     #define bfd_mach_sparc_sparclet        2
     534     #define bfd_mach_sparc_sparclite       3
     535     #define bfd_mach_sparc_v8plus          4
     536     #define bfd_mach_sparc_v8plusa         5 /* with ultrasparc add'ns.  */
     537     #define bfd_mach_sparc_sparclite_le    6
     538     #define bfd_mach_sparc_v9              7
     539     #define bfd_mach_sparc_v9a             8 /* with ultrasparc add'ns.  */
     540     #define bfd_mach_sparc_v8plusb         9 /* with cheetah add'ns.  */
     541     #define bfd_mach_sparc_v9b             10 /* with cheetah add'ns.  */
     542     /* Nonzero if MACH has the v9 instruction set.  */
     543     #define bfd_mach_sparc_v9_p(mach) \
     544       ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9b \
     545        && (mach) != bfd_mach_sparc_sparclite_le)
     546       bfd_arch_mips,      /* MIPS Rxxxx */
     547     #define bfd_mach_mips3000              3000
     548     #define bfd_mach_mips3900              3900
     549     #define bfd_mach_mips4000              4000
     550     #define bfd_mach_mips4010              4010
     551     #define bfd_mach_mips4100              4100
     552     #define bfd_mach_mips4111              4111
     553     #define bfd_mach_mips4120              4120
     554     #define bfd_mach_mips4300              4300
     555     #define bfd_mach_mips4400              4400
     556     #define bfd_mach_mips4600              4600
     557     #define bfd_mach_mips4650              4650
     558     #define bfd_mach_mips5000              5000
     559     #define bfd_mach_mips5400              5400
     560     #define bfd_mach_mips5500              5500
     561     #define bfd_mach_mips6000              6000
     562     #define bfd_mach_mips8000              8000
     563     #define bfd_mach_mips10000             10000
     564     #define bfd_mach_mips12000             12000
     565     #define bfd_mach_mips16                16
     566     #define bfd_mach_mips5                 5
     567     #define bfd_mach_mips_sb1              12310201 /* octal 'SB', 01 */
     568     #define bfd_mach_mipsisa32             32
     569     #define bfd_mach_mipsisa32r2           33
     570     #define bfd_mach_mipsisa64             64
     571       bfd_arch_i386,      /* Intel 386 */
     572     #define bfd_mach_i386_i386 1
     573     #define bfd_mach_i386_i8086 2
     574     #define bfd_mach_i386_i386_intel_syntax 3
     575     #define bfd_mach_x86_64 64
     576     #define bfd_mach_x86_64_intel_syntax 65
     577       bfd_arch_we32k,     /* AT&T WE32xxx */
     578       bfd_arch_tahoe,     /* CCI/Harris Tahoe */
     579       bfd_arch_i860,      /* Intel 860 */
     580       bfd_arch_i370,      /* IBM 360/370 Mainframes */
     581       bfd_arch_romp,      /* IBM ROMP PC/RT */
     582       bfd_arch_alliant,   /* Alliant */
     583       bfd_arch_convex,    /* Convex */
     584       bfd_arch_m88k,      /* Motorola 88xxx */
     585       bfd_arch_m98k,      /* Motorola 98xxx */
     586       bfd_arch_pyramid,   /* Pyramid Technology */
     587       bfd_arch_h8300,     /* Renesas H8/300 (formerly Hitachi H8/300) */
     588     #define bfd_mach_h8300    1
     589     #define bfd_mach_h8300h   2
     590     #define bfd_mach_h8300s   3
     591     #define bfd_mach_h8300hn  4
     592     #define bfd_mach_h8300sn  5
     593       bfd_arch_pdp11,     /* DEC PDP-11 */
     594       bfd_arch_powerpc,   /* PowerPC */
     595     #define bfd_mach_ppc           32
     596     #define bfd_mach_ppc64         64
     597     #define bfd_mach_ppc_403       403
     598     #define bfd_mach_ppc_403gc     4030
     599     #define bfd_mach_ppc_505       505
     600     #define bfd_mach_ppc_601       601
     601     #define bfd_mach_ppc_602       602
     602     #define bfd_mach_ppc_603       603
     603     #define bfd_mach_ppc_ec603e    6031
     604     #define bfd_mach_ppc_604       604
     605     #define bfd_mach_ppc_620       620
     606     #define bfd_mach_ppc_630       630
     607     #define bfd_mach_ppc_750       750
     608     #define bfd_mach_ppc_860       860
     609     #define bfd_mach_ppc_a35       35
     610     #define bfd_mach_ppc_rs64ii    642
     611     #define bfd_mach_ppc_rs64iii   643
     612     #define bfd_mach_ppc_7400      7400
     613     #define bfd_mach_ppc_e500      500
     614       bfd_arch_rs6000,    /* IBM RS/6000 */
     615     #define bfd_mach_rs6k          6000
     616     #define bfd_mach_rs6k_rs1      6001
     617     #define bfd_mach_rs6k_rsc      6003
     618     #define bfd_mach_rs6k_rs2      6002
     619       bfd_arch_hppa,      /* HP PA RISC */
     620       bfd_arch_d10v,      /* Mitsubishi D10V */
     621     #define bfd_mach_d10v          1
     622     #define bfd_mach_d10v_ts2      2
     623     #define bfd_mach_d10v_ts3      3
     624       bfd_arch_d30v,      /* Mitsubishi D30V */
     625       bfd_arch_dlx,       /* DLX */
     626       bfd_arch_m68hc11,   /* Motorola 68HC11 */
     627       bfd_arch_m68hc12,   /* Motorola 68HC12 */
     628     #define bfd_mach_m6812_default 0
     629     #define bfd_mach_m6812         1
     630     #define bfd_mach_m6812s        2
     631       bfd_arch_z8k,       /* Zilog Z8000 */
     632     #define bfd_mach_z8001         1
     633     #define bfd_mach_z8002         2
     634       bfd_arch_h8500,     /* Renesas H8/500 (formerly Hitachi H8/500) */
     635       bfd_arch_sh,        /* Renesas / SuperH SH (formerly Hitachi SH) */
     636     #define bfd_mach_sh            1
     637     #define bfd_mach_sh2        0x20
     638     #define bfd_mach_sh_dsp     0x2d
     639     #define bfd_mach_sh2e       0x2e
     640     #define bfd_mach_sh3        0x30
     641     #define bfd_mach_sh3_dsp    0x3d
     642     #define bfd_mach_sh3e       0x3e
     643     #define bfd_mach_sh4        0x40
     644     #define bfd_mach_sh5        0x50
     645       bfd_arch_alpha,     /* Dec Alpha */
     646     #define bfd_mach_alpha_ev4  0x10
     647     #define bfd_mach_alpha_ev5  0x20
     648     #define bfd_mach_alpha_ev6  0x30
     649       bfd_arch_arm,       /* Advanced Risc Machines ARM.  */
     650     #define bfd_mach_arm_unknown   0
     651     #define bfd_mach_arm_2         1
     652     #define bfd_mach_arm_2a        2
     653     #define bfd_mach_arm_3         3
     654     #define bfd_mach_arm_3M        4
     655     #define bfd_mach_arm_4         5
     656     #define bfd_mach_arm_4T        6
     657     #define bfd_mach_arm_5         7
     658     #define bfd_mach_arm_5T        8
     659     #define bfd_mach_arm_5TE       9
     660     #define bfd_mach_arm_XScale    10
     661     #define bfd_mach_arm_ep9312    11
     662     #define bfd_mach_arm_iWMMXt    12
     663       bfd_arch_ns32k,     /* National Semiconductors ns32000 */
     664       bfd_arch_w65,       /* WDC 65816 */
     665       bfd_arch_tic30,     /* Texas Instruments TMS320C30 */
     666       bfd_arch_tic4x,     /* Texas Instruments TMS320C3X/4X */
     667     #define bfd_mach_tic3x         30
     668     #define bfd_mach_tic4x         40
     669       bfd_arch_tic54x,    /* Texas Instruments TMS320C54X */
     670       bfd_arch_tic80,     /* TI TMS320c80 (MVP) */
     671       bfd_arch_v850,      /* NEC V850 */
     672     #define bfd_mach_v850          1
     673     #define bfd_mach_v850e         'E'
     674       bfd_arch_arc,       /* ARC Cores */
     675     #define bfd_mach_arc_5         5
     676     #define bfd_mach_arc_6         6
     677     #define bfd_mach_arc_7         7
     678     #define bfd_mach_arc_8         8
     679       bfd_arch_m32r,      /* Renesas M32R (formerly Mitsubishi M32R/D) */
     680     #define bfd_mach_m32r          1 /* For backwards compatibility.  */
     681     #define bfd_mach_m32rx         'x'
     682       bfd_arch_mn10200,   /* Matsushita MN10200 */
     683       bfd_arch_mn10300,   /* Matsushita MN10300 */
     684     #define bfd_mach_mn10300               300
     685     #define bfd_mach_am33          330
     686       bfd_arch_fr30,
     687     #define bfd_mach_fr30          0x46523330
     688       bfd_arch_frv,
     689     #define bfd_mach_frv           1
     690     #define bfd_mach_frvsimple     2
     691     #define bfd_mach_fr300         300
     692     #define bfd_mach_fr400         400
     693     #define bfd_mach_frvtomcat     499     /* fr500 prototype */
     694     #define bfd_mach_fr500         500
     695       bfd_arch_mcore,
     696       bfd_arch_ia64,      /* HP/Intel ia64 */
     697     #define bfd_mach_ia64_elf64    64
     698     #define bfd_mach_ia64_elf32    32
     699       bfd_arch_ip2k,      /* Ubicom IP2K microcontrollers. */
     700     #define bfd_mach_ip2022        1
     701     #define bfd_mach_ip2022ext     2
     702      bfd_arch_iq2000,     /* Vitesse IQ2000.  */
     703     #define bfd_mach_iq2000        1
     704     #define bfd_mach_iq10          2
     705       bfd_arch_pj,
     706       bfd_arch_avr,       /* Atmel AVR microcontrollers.  */
     707     #define bfd_mach_avr1          1
     708     #define bfd_mach_avr2          2
     709     #define bfd_mach_avr3          3
     710     #define bfd_mach_avr4          4
     711     #define bfd_mach_avr5          5
     712       bfd_arch_cris,      /* Axis CRIS */
     713       bfd_arch_s390,      /* IBM s390 */
     714     #define bfd_mach_s390_31       31
     715     #define bfd_mach_s390_64       64
     716       bfd_arch_openrisc,  /* OpenRISC */
     717       bfd_arch_mmix,      /* Donald Knuth's educational processor.  */
     718       bfd_arch_xstormy16,
     719     #define bfd_mach_xstormy16     1
     720       bfd_arch_msp430,    /* Texas Instruments MSP430 architecture.  */
     721     #define bfd_mach_msp110         110
     722     #define bfd_mach_msp11          11
     723     #define bfd_mach_msp12          12
     724     #define bfd_mach_msp13          13
     725     #define bfd_mach_msp14          14
     726     #define bfd_mach_msp41          41
     727     #define bfd_mach_msp31          31
     728     #define bfd_mach_msp32          32
     729     #define bfd_mach_msp33          33
     730     #define bfd_mach_msp43          43
     731     #define bfd_mach_msp44          44
     732     #define bfd_mach_msp15          15
     733     #define bfd_mach_msp16          16
     734       bfd_arch_xtensa,    /* Tensilica's Xtensa cores.  */
     735     #define bfd_mach_xtensa        1
     736       bfd_arch_last
     737       };
     738
     739bfd_arch_info
     740-------------
     741
     742   *Description*
     743This structure contains information on architectures for use within BFD.
     744
     745     typedef struct bfd_arch_info
     746     {
     747       int bits_per_word;
     748       int bits_per_address;
     749       int bits_per_byte;
     750       enum bfd_architecture arch;
     751       unsigned long mach;
     752       const char *arch_name;
     753       const char *printable_name;
     754       unsigned int section_align_power;
     755       /* TRUE if this is the default machine for the architecture.
     756          The default arch should be the first entry for an arch so that
     757          all the entries for that arch can be accessed via `next'.  */
     758       bfd_boolean the_default;
     759       const struct bfd_arch_info * (*compatible)
     760            PARAMS ((const struct bfd_arch_info *a,
     761                     const struct bfd_arch_info *b));
     762     
     763       bfd_boolean (*scan) PARAMS ((const struct bfd_arch_info *, const char *));
     764     
     765       const struct bfd_arch_info *next;
     766     }
     767     bfd_arch_info_type;
     768
     769`bfd_printable_name'
     770....................
     771
     772   *Synopsis*
     773     const char *bfd_printable_name(bfd *abfd);
     774   *Description*
     775Return a printable string representing the architecture and machine
     776from the pointer to the architecture info structure.
     777
     778`bfd_scan_arch'
     779...............
     780
     781   *Synopsis*
     782     const bfd_arch_info_type *bfd_scan_arch(const char *string);
     783   *Description*
     784Figure out if BFD supports any cpu which could be described with the
     785name STRING.  Return a pointer to an `arch_info' structure if a machine
     786is found, otherwise NULL.
     787
     788`bfd_arch_list'
     789...............
     790
     791   *Synopsis*
     792     const char **bfd_arch_list(void);
     793   *Description*
     794Return a freshly malloced NULL-terminated vector of the names of all
     795the valid BFD architectures.  Do not modify the names.
     796
     797`bfd_arch_get_compatible'
     798.........................
     799
     800   *Synopsis*
     801     const bfd_arch_info_type *bfd_arch_get_compatible(
     802         const bfd *abfd,
     803         const bfd *bbfd,
     804         bfd_boolean accept_unknowns);
     805   *Description*
     806Determine whether two BFDs' architectures and machine types are
     807compatible.  Calculates the lowest common denominator between the two
     808architectures and machine types implied by the BFDs and returns a
     809pointer to an `arch_info' structure describing the compatible machine.
     810
     811`bfd_default_arch_struct'
     812.........................
     813
     814   *Description*
     815The `bfd_default_arch_struct' is an item of `bfd_arch_info_type' which
     816has been initialized to a fairly generic state.  A BFD starts life by
     817pointing to this structure, until the correct back end has determined
     818the real architecture of the file.
     819     extern const bfd_arch_info_type bfd_default_arch_struct;
     820
     821`bfd_set_arch_info'
     822...................
     823
     824   *Synopsis*
     825     void bfd_set_arch_info(bfd *abfd, const bfd_arch_info_type *arg);
     826   *Description*
     827Set the architecture info of ABFD to ARG.
     828
     829`bfd_default_set_arch_mach'
     830...........................
     831
     832   *Synopsis*
     833     bfd_boolean bfd_default_set_arch_mach(bfd *abfd,
     834         enum bfd_architecture arch,
     835         unsigned long mach);
     836   *Description*
     837Set the architecture and machine type in BFD ABFD to ARCH and MACH.
     838Find the correct pointer to a structure and insert it into the
     839`arch_info' pointer.
     840
     841`bfd_get_arch'
     842..............
     843
     844   *Synopsis*
     845     enum bfd_architecture bfd_get_arch(bfd *abfd);
     846   *Description*
     847Return the enumerated type which describes the BFD ABFD's architecture.
     848
     849`bfd_get_mach'
     850..............
     851
     852   *Synopsis*
     853     unsigned long bfd_get_mach(bfd *abfd);
     854   *Description*
     855Return the long type which describes the BFD ABFD's machine.
     856
     857`bfd_arch_bits_per_byte'
     858........................
     859
     860   *Synopsis*
     861     unsigned int bfd_arch_bits_per_byte(bfd *abfd);
     862   *Description*
     863Return the number of bits in one of the BFD ABFD's architecture's bytes.
     864
     865`bfd_arch_bits_per_address'
     866...........................
     867
     868   *Synopsis*
     869     unsigned int bfd_arch_bits_per_address(bfd *abfd);
     870   *Description*
     871Return the number of bits in one of the BFD ABFD's architecture's
     872addresses.
     873
     874`bfd_default_compatible'
     875........................
     876
     877   *Synopsis*
     878     const bfd_arch_info_type *bfd_default_compatible
     879        (const bfd_arch_info_type *a,
     880         const bfd_arch_info_type *b);
     881   *Description*
     882The default function for testing for compatibility.
     883
     884`bfd_default_scan'
     885..................
     886
     887   *Synopsis*
     888     bfd_boolean bfd_default_scan(const struct bfd_arch_info *info, const char *string);
     889   *Description*
     890The default function for working out whether this is an architecture
     891hit and a machine hit.
     892
     893`bfd_get_arch_info'
     894...................
     895
     896   *Synopsis*
     897     const bfd_arch_info_type * bfd_get_arch_info(bfd *abfd);
     898   *Description*
     899Return the architecture info struct in ABFD.
     900
     901`bfd_lookup_arch'
     902.................
     903
     904   *Synopsis*
     905     const bfd_arch_info_type *bfd_lookup_arch
     906        (enum bfd_architecture
     907         arch,
     908         unsigned long machine);
     909   *Description*
     910Look for the architecure info structure which matches the arguments
     911ARCH and MACHINE. A machine of 0 matches the machine/architecture
     912structure which marks itself as the default.
     913
     914`bfd_printable_arch_mach'
     915.........................
     916
     917   *Synopsis*
     918     const char *bfd_printable_arch_mach
     919        (enum bfd_architecture arch, unsigned long machine);
     920   *Description*
     921Return a printable string representing the architecture and machine
     922type.
     923
     924   This routine is depreciated.
     925
     926`bfd_octets_per_byte'
     927.....................
     928
     929   *Synopsis*
     930     unsigned int bfd_octets_per_byte(bfd *abfd);
     931   *Description*
     932Return the number of octets (8-bit quantities) per target byte (minimum
     933addressable unit).  In most cases, this will be one, but some DSP
     934targets have 16, 32, or even 48 bits per byte.
     935
     936`bfd_arch_mach_octets_per_byte'
     937...............................
     938
     939   *Synopsis*
     940     unsigned int bfd_arch_mach_octets_per_byte(enum bfd_architecture arch,
     941         unsigned long machine);
     942   *Description*
     943See bfd_octets_per_byte.
     944
     945   This routine is provided for those cases where a bfd * is not
     946available
    89947
    90948
    91 File: bfd.info,  Node: Adding Symbols to the Hash Table,  Next: Performing the Final Link,  Prev: Creating a Linker Hash Table,  Up: Linker Functions
    92 
    93 Adding symbols to the hash table
    94 --------------------------------
    95 
    96    The linker proper will call the `_bfd_link_add_symbols' entry point
    97 for each object file or archive which is to be linked (typically these
    98 are the files named on the command line, but some may also come from
    99 the linker script).  The entry point is responsible for examining the
    100 file.  For an object file, BFD must add any relevant symbol information
    101 to the hash table.  For an archive, BFD must determine which elements
    102 of the archive should be used and adding them to the link.
    103 
    104    The a.out version of this entry point is
    105 `NAME(aout,link_add_symbols)'.
    106 
    107 * Menu:
    108 
    109 * Differing file formats::
    110 * Adding symbols from an object file::
    111 * Adding symbols from an archive::
    112 
    113 
    114 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
    115 
    116 Differing file formats
    117 ......................
    118 
    119    Normally all the files involved in a link will be of the same
    120 format, but it is also possible to link together different format
    121 object files, and the back end must support that.  The
    122 `_bfd_link_add_symbols' entry point is called via the target vector of
    123 the file to be added.  This has an important consequence: the function
    124 may not assume that the hash table is the type created by the
    125 corresponding `_bfd_link_hash_table_create' vector.  All the
    126 `_bfd_link_add_symbols' function can assume about the hash table is
    127 that it is derived from `struct bfd_link_hash_table'.
    128 
    129    Sometimes the `_bfd_link_add_symbols' function must store some
    130 information in the hash table entry to be used by the `_bfd_final_link'
    131 function.  In such a case the `creator' field of the hash table must be
    132 checked to make sure that the hash table was created by an object file
    133 of the same format.
    134 
    135    The `_bfd_final_link' routine must be prepared to handle a hash
    136 entry without any extra information added by the
    137 `_bfd_link_add_symbols' function.  A hash entry without extra
    138 information will also occur when the linker script directs the linker
    139 to create a symbol.  Note that, regardless of how a hash table entry is
    140 added, all the fields will be initialized to some sort of null value by
    141 the hash table entry initialization function.
    142 
    143    See `ecoff_link_add_externals' for an example of how to check the
    144 `creator' field before saving information (in this case, the ECOFF
    145 external symbol debugging information) in a hash table entry.
    146 
    147 
    148 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
    149 
    150 Adding symbols from an object file
    151 ..................................
    152 
    153    When the `_bfd_link_add_symbols' routine is passed an object file,
    154 it must add all externally visible symbols in that object file to the
    155 hash table.  The actual work of adding the symbol to the hash table is
    156 normally handled by the function `_bfd_generic_link_add_one_symbol'.
    157 The `_bfd_link_add_symbols' routine is responsible for reading all the
    158 symbols from the object file and passing the correct information to
    159 `_bfd_generic_link_add_one_symbol'.
    160 
    161    The `_bfd_link_add_symbols' routine should not use
    162 `bfd_canonicalize_symtab' to read the symbols.  The point of providing
    163 this routine is to avoid the overhead of converting the symbols into
    164 generic `asymbol' structures.
    165 
    166    `_bfd_generic_link_add_one_symbol' handles the details of combining
    167 common symbols, warning about multiple definitions, and so forth.  It
    168 takes arguments which describe the symbol to add, notably symbol flags,
    169 a section, and an offset.  The symbol flags include such things as
    170 `BSF_WEAK' or `BSF_INDIRECT'.  The section is a section in the object
    171 file, or something like `bfd_und_section_ptr' for an undefined symbol
    172 or `bfd_com_section_ptr' for a common symbol.
    173 
    174    If the `_bfd_final_link' routine is also going to need to read the
    175 symbol information, the `_bfd_link_add_symbols' routine should save it
    176 somewhere attached to the object file BFD.  However, the information
    177 should only be saved if the `keep_memory' field of the `info' argument
    178 is true, so that the `-no-keep-memory' linker switch is effective.
    179 
    180    The a.out function which adds symbols from an object file is
    181 `aout_link_add_object_symbols', and most of the interesting work is in
    182 `aout_link_add_symbols'.  The latter saves pointers to the hash tables
    183 entries created by `_bfd_generic_link_add_one_symbol' indexed by symbol
    184 number, so that the `_bfd_final_link' routine does not have to call the
    185 hash table lookup routine to locate the entry.
    186 
    187 
    188 File: bfd.info,  Node: Adding symbols from an archive,  Prev: Adding symbols from an object file,  Up: Adding Symbols to the Hash Table
    189 
    190 Adding symbols from an archive
    191 ..............................
    192 
    193    When the `_bfd_link_add_symbols' routine is passed an archive, it
    194 must look through the symbols defined by the archive and decide which
    195 elements of the archive should be included in the link.  For each such
    196 element it must call the `add_archive_element' linker callback, and it
    197 must add the symbols from the object file to the linker hash table.
    198 
    199    In most cases the work of looking through the symbols in the archive
    200 should be done by the `_bfd_generic_link_add_archive_symbols' function.
    201 This function builds a hash table from the archive symbol table and
    202 looks through the list of undefined symbols to see which elements
    203 should be included.  `_bfd_generic_link_add_archive_symbols' is passed
    204 a function to call to make the final decision about adding an archive
    205 element to the link and to do the actual work of adding the symbols to
    206 the linker hash table.
    207 
    208    The function passed to `_bfd_generic_link_add_archive_symbols' must
    209 read the symbols of the archive element and decide whether the archive
    210 element should be included in the link.  If the element is to be
    211 included, the `add_archive_element' linker callback routine must be
    212 called with the element as an argument, and the elements symbols must
    213 be added to the linker hash table just as though the element had itself
    214 been passed to the `_bfd_link_add_symbols' function.
    215 
    216    When the a.out `_bfd_link_add_symbols' function receives an archive,
    217 it calls `_bfd_generic_link_add_archive_symbols' passing
    218 `aout_link_check_archive_element' as the function argument.
    219 `aout_link_check_archive_element' calls `aout_link_check_ar_symbols'.
    220 If the latter decides to add the element (an element is only added if
    221 it provides a real, non-common, definition for a previously undefined
    222 or common symbol) it calls the `add_archive_element' callback and then
    223 `aout_link_check_archive_element' calls `aout_link_add_symbols' to
    224 actually add the symbols to the linker hash table.
    225 
    226    The ECOFF back end is unusual in that it does not normally call
    227 `_bfd_generic_link_add_archive_symbols', because ECOFF archives already
    228 contain a hash table of symbols.  The ECOFF back end searches the
    229 archive itself to avoid the overhead of creating a new hash table.
    230 
    231 
    232 File: bfd.info,  Node: Performing the Final Link,  Prev: Adding Symbols to the Hash Table,  Up: Linker Functions
    233 
    234 Performing the final link
    235 -------------------------
    236 
    237    When all the input files have been processed, the linker calls the
    238 `_bfd_final_link' entry point of the output BFD.  This routine is
    239 responsible for producing the final output file, which has several
    240 aspects.  It must relocate the contents of the input sections and copy
    241 the data into the output sections.  It must build an output symbol
    242 table including any local symbols from the input files and the global
    243 symbols from the hash table.  When producing relocateable output, it
    244 must modify the input relocs and write them into the output file.
    245 There may also be object format dependent work to be done.
    246 
    247    The linker will also call the `write_object_contents' entry point
    248 when the BFD is closed.  The two entry points must work together in
    249 order to produce the correct output file.
    250 
    251    The details of how this works are inevitably dependent upon the
    252 specific object file format.  The a.out `_bfd_final_link' routine is
    253 `NAME(aout,final_link)'.
    254 
    255 * Menu:
    256 
    257 * Information provided by the linker::
    258 * Relocating the section contents::
    259 * Writing the symbol table::
    260 
    261 
    262 File: bfd.info,  Node: Information provided by the linker,  Next: Relocating the section contents,  Prev: Performing the Final Link,  Up: Performing the Final Link
    263 
    264 Information provided by the linker
    265 ..................................
    266 
    267    Before the linker calls the `_bfd_final_link' entry point, it sets
    268 up some data structures for the function to use.
    269 
    270    The `input_bfds' field of the `bfd_link_info' structure will point
    271 to a list of all the input files included in the link.  These files are
    272 linked through the `link_next' field of the `bfd' structure.
    273 
    274    Each section in the output file will have a list of `link_order'
    275 structures attached to the `link_order_head' field (the `link_order'
    276 structure is defined in `bfdlink.h').  These structures describe how to
    277 create the contents of the output section in terms of the contents of
    278 various input sections, fill constants, and, eventually, other types of
    279 information.  They also describe relocs that must be created by the BFD
    280 backend, but do not correspond to any input file; this is used to
    281 support -Ur, which builds constructors while generating a relocateable
    282 object file.
    283 
    284 
    285 File: bfd.info,  Node: Relocating the section contents,  Next: Writing the symbol table,  Prev: Information provided by the linker,  Up: Performing the Final Link
    286 
    287 Relocating the section contents
    288 ...............................
    289 
    290    The `_bfd_final_link' function should look through the `link_order'
    291 structures attached to each section of the output file.  Each
    292 `link_order' structure should either be handled specially, or it should
    293 be passed to the function `_bfd_default_link_order' which will do the
    294 right thing (`_bfd_default_link_order' is defined in `linker.c').
    295 
    296    For efficiency, a `link_order' of type `bfd_indirect_link_order'
    297 whose associated section belongs to a BFD of the same format as the
    298 output BFD must be handled specially.  This type of `link_order'
    299 describes part of an output section in terms of a section belonging to
    300 one of the input files.  The `_bfd_final_link' function should read the
    301 contents of the section and any associated relocs, apply the relocs to
    302 the section contents, and write out the modified section contents.  If
    303 performing a relocateable link, the relocs themselves must also be
    304 modified and written out.
    305 
    306    The functions `_bfd_relocate_contents' and
    307 `_bfd_final_link_relocate' provide some general support for performing
    308 the actual relocations, notably overflow checking.  Their arguments
    309 include information about the symbol the relocation is against and a
    310 `reloc_howto_type' argument which describes the relocation to perform.
    311 These functions are defined in `reloc.c'.
    312 
    313    The a.out function which handles reading, relocating, and writing
    314 section contents is `aout_link_input_section'.  The actual relocation
    315 is done in `aout_link_input_section_std' and
    316 `aout_link_input_section_ext'.
    317 
    318 
    319 File: bfd.info,  Node: Writing the symbol table,  Prev: Relocating the section contents,  Up: Performing the Final Link
    320 
    321 Writing the symbol table
    322 ........................
    323 
    324    The `_bfd_final_link' function must gather all the symbols in the
    325 input files and write them out.  It must also write out all the symbols
    326 in the global hash table.  This must be controlled by the `strip' and
    327 `discard' fields of the `bfd_link_info' structure.
    328 
    329    The local symbols of the input files will not have been entered into
    330 the linker hash table.  The `_bfd_final_link' routine must consider
    331 each input file and include the symbols in the output file.  It may be
    332 convenient to do this when looking through the `link_order' structures,
    333 or it may be done by stepping through the `input_bfds' list.
    334 
    335    The `_bfd_final_link' routine must also traverse the global hash
    336 table to gather all the externally visible symbols.  It is possible
    337 that most of the externally visible symbols may be written out when
    338 considering the symbols of each input file, but it is still necessary
    339 to traverse the hash table since the linker script may have defined
    340 some symbols that are not in any of the input files.
    341 
    342    The `strip' field of the `bfd_link_info' structure controls which
    343 symbols are written out.  The possible values are listed in
    344 `bfdlink.h'.  If the value is `strip_some', then the `keep_hash' field
    345 of the `bfd_link_info' structure is a hash table of symbols to keep;
    346 each symbol should be looked up in this hash table, and only symbols
    347 which are present should be included in the output file.
    348 
    349    If the `strip' field of the `bfd_link_info' structure permits local
    350 symbols to be written out, the `discard' field is used to further
    351 controls which local symbols are included in the output file.  If the
    352 value is `discard_l', then all local symbols which begin with a certain
    353 prefix are discarded; this is controlled by the
    354 `bfd_is_local_label_name' entry point.
    355 
    356    The a.out backend handles symbols by calling
    357 `aout_link_write_symbols' on each input BFD and then traversing the
    358 global hash table with the function `aout_link_write_other_symbol'.  It
    359 builds a string table while writing out the symbols, which is written
    360 to the output file at the end of `NAME(aout,final_link)'.
    361 
    362 `bfd_link_split_section'
    363 ........................
    364 
    365    *Synopsis*
    366      boolean bfd_link_split_section(bfd *abfd, asection *sec);
    367    *Description*
    368 Return nonzero if SEC should be split during a reloceatable or final
    369 link.
    370      #define bfd_link_split_section(abfd, sec) \
    371             BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec))
    372 
    373 
    374 File: bfd.info,  Node: Hash Tables,  Prev: Linker Functions,  Up: BFD front end
    375 
    376 Hash Tables
    377 ===========
    378 
    379    BFD provides a simple set of hash table functions.  Routines are
    380 provided to initialize a hash table, to free a hash table, to look up a
    381 string in a hash table and optionally create an entry for it, and to
    382 traverse a hash table.  There is currently no routine to delete an
    383 string from a hash table.
    384 
    385    The basic hash table does not permit any data to be stored with a
    386 string.  However, a hash table is designed to present a base class from
    387 which other types of hash tables may be derived.  These derived types
    388 may store additional information with the string.  Hash tables were
    389 implemented in this way, rather than simply providing a data pointer in
    390 a hash table entry, because they were designed for use by the linker
    391 back ends.  The linker may create thousands of hash table entries, and
    392 the overhead of allocating private data and storing and following
    393 pointers becomes noticeable.
    394 
    395    The basic hash table code is in `hash.c'.
    396 
    397 * Menu:
    398 
    399 * Creating and Freeing a Hash Table::
    400 * Looking Up or Entering a String::
    401 * Traversing a Hash Table::
    402 * Deriving a New Hash Table Type::
    403 
    404 
    405 File: bfd.info,  Node: Creating and Freeing a Hash Table,  Next: Looking Up or Entering a String,  Prev: Hash Tables,  Up: Hash Tables
    406 
    407 Creating and freeing a hash table
    408 ---------------------------------
    409 
    410    To create a hash table, create an instance of a `struct
    411 bfd_hash_table' (defined in `bfd.h') and call `bfd_hash_table_init' (if
    412 you know approximately how many entries you will need, the function
    413 `bfd_hash_table_init_n', which takes a SIZE argument, may be used).
    414 `bfd_hash_table_init' returns `false' if some sort of error occurs.
    415 
    416    The function `bfd_hash_table_init' take as an argument a function to
    417 use to create new entries.  For a basic hash table, use the function
    418 `bfd_hash_newfunc'.  *Note Deriving a New Hash Table Type::, for why
    419 you would want to use a different value for this argument.
    420 
    421    `bfd_hash_table_init' will create an objalloc which will be used to
    422 allocate new entries.  You may allocate memory on this objalloc using
    423 `bfd_hash_allocate'.
    424 
    425    Use `bfd_hash_table_free' to free up all the memory that has been
    426 allocated for a hash table.  This will not free up the `struct
    427 bfd_hash_table' itself, which you must provide.
    428 
    429 
    430 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
    431 
    432 Looking up or entering a string
    433 -------------------------------
    434 
    435    The function `bfd_hash_lookup' is used both to look up a string in
    436 the hash table and to create a new entry.
    437 
    438    If the CREATE argument is `false', `bfd_hash_lookup' will look up a
    439 string.  If the string is found, it will returns a pointer to a `struct
    440 bfd_hash_entry'.  If the string is not found in the table
    441 `bfd_hash_lookup' will return `NULL'.  You should not modify any of the
    442 fields in the returns `struct bfd_hash_entry'.
    443 
    444    If the CREATE argument is `true', the string will be entered into
    445 the hash table if it is not already there.  Either way a pointer to a
    446 `struct bfd_hash_entry' will be returned, either to the existing
    447 structure or to a newly created one.  In this case, a `NULL' return
    448 means that an error occurred.
    449 
    450    If the CREATE argument is `true', and a new entry is created, the
    451 COPY argument is used to decide whether to copy the string onto the
    452 hash table objalloc or not.  If COPY is passed as `false', you must be
    453 careful not to deallocate or modify the string as long as the hash table
    454 exists.
    455 
    456 
    457 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
    458 
    459 Traversing a hash table
    460 -----------------------
    461 
    462    The function `bfd_hash_traverse' may be used to traverse a hash
    463 table, calling a function on each element.  The traversal is done in a
    464 random order.
    465 
    466    `bfd_hash_traverse' takes as arguments a function and a generic
    467 `void *' pointer.  The function is called with a hash table entry (a
    468 `struct bfd_hash_entry *') and the generic pointer passed to
    469 `bfd_hash_traverse'.  The function must return a `boolean' value, which
    470 indicates whether to continue traversing the hash table.  If the
    471 function returns `false', `bfd_hash_traverse' will stop the traversal
    472 and return immediately.
    473 
    474 
    475 File: bfd.info,  Node: Deriving a New Hash Table Type,  Prev: Traversing a Hash Table,  Up: Hash Tables
    476 
    477 Deriving a new hash table type
    478 ------------------------------
    479 
    480    Many uses of hash tables want to store additional information which
    481 each entry in the hash table.  Some also find it convenient to store
    482 additional information with the hash table itself.  This may be done
    483 using a derived hash table.
    484 
    485    Since C is not an object oriented language, creating a derived hash
    486 table requires sticking together some boilerplate routines with a few
    487 differences specific to the type of hash table you want to create.
    488 
    489    An example of a derived hash table is the linker hash table.  The
    490 structures for this are defined in `bfdlink.h'.  The functions are in
    491 `linker.c'.
    492 
    493    You may also derive a hash table from an already derived hash table.
    494 For example, the a.out linker backend code uses a hash table derived
    495 from the linker hash table.
    496 
    497 * Menu:
    498 
    499 * Define the Derived Structures::
    500 * Write the Derived Creation Routine::
    501 * Write Other Derived Routines::
    502 
    503 
    504 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
    505 
    506 Define the derived structures
    507 .............................
    508 
    509    You must define a structure for an entry in the hash table, and a
    510 structure for the hash table itself.
    511 
    512    The first field in the structure for an entry in the hash table must
    513 be of the type used for an entry in the hash table you are deriving
    514 from.  If you are deriving from a basic hash table this is `struct
    515 bfd_hash_entry', which is defined in `bfd.h'.  The first field in the
    516 structure for the hash table itself must be of the type of the hash
    517 table you are deriving from itself.  If you are deriving from a basic
    518 hash table, this is `struct bfd_hash_table'.
    519 
    520    For example, the linker hash table defines `struct
    521 bfd_link_hash_entry' (in `bfdlink.h').  The first field, `root', is of
    522 type `struct bfd_hash_entry'.  Similarly, the first field in `struct
    523 bfd_link_hash_table', `table', is of type `struct bfd_hash_table'.
    524 
    525 
    526 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
    527 
    528 Write the derived creation routine
    529 ..................................
    530 
    531    You must write a routine which will create and initialize an entry
    532 in the hash table.  This routine is passed as the function argument to
    533 `bfd_hash_table_init'.
    534 
    535    In order to permit other hash tables to be derived from the hash
    536 table you are creating, this routine must be written in a standard way.
    537 
    538    The first argument to the creation routine is a pointer to a hash
    539 table entry.  This may be `NULL', in which case the routine should
    540 allocate the right amount of space.  Otherwise the space has already
    541 been allocated by a hash table type derived from this one.
    542 
    543    After allocating space, the creation routine must call the creation
    544 routine of the hash table type it is derived from, passing in a pointer
    545 to the space it just allocated.  This will initialize any fields used
    546 by the base hash table.
    547 
    548    Finally the creation routine must initialize any local fields for
    549 the new hash table type.
    550 
    551    Here is a boilerplate example of a creation routine.  FUNCTION_NAME
    552 is the name of the routine.  ENTRY_TYPE is the type of an entry in the
    553 hash table you are creating.  BASE_NEWFUNC is the name of the creation
    554 routine of the hash table type your hash table is derived from.
    555 
    556      struct bfd_hash_entry *
    557      FUNCTION_NAME (entry, table, string)
    558           struct bfd_hash_entry *entry;
    559           struct bfd_hash_table *table;
    560           const char *string;
    561      {
    562        struct ENTRY_TYPE *ret = (ENTRY_TYPE *) entry;
    563      
    564       /* Allocate the structure if it has not already been allocated by a
    565          derived class.  */
    566        if (ret == (ENTRY_TYPE *) NULL)
    567          {
    568            ret = ((ENTRY_TYPE *)
    569                   bfd_hash_allocate (table, sizeof (ENTRY_TYPE)));
    570            if (ret == (ENTRY_TYPE *) NULL)
    571              return NULL;
    572          }
    573      
    574       /* Call the allocation method of the base class.  */
    575        ret = ((ENTRY_TYPE *)
    576              BASE_NEWFUNC ((struct bfd_hash_entry *) ret, table, string));
    577      
    578       /* Initialize the local fields here.  */
    579      
    580        return (struct bfd_hash_entry *) ret;
    581      }
    582    *Description*
    583 The creation routine for the linker hash table, which is in `linker.c',
    584 looks just like this example.  FUNCTION_NAME is
    585 `_bfd_link_hash_newfunc'.  ENTRY_TYPE is `struct bfd_link_hash_entry'.
    586 BASE_NEWFUNC is `bfd_hash_newfunc', the creation routine for a basic
    587 hash table.
    588 
    589    `_bfd_link_hash_newfunc' also initializes the local fields in a
    590 linker hash table entry: `type', `written' and `next'.
    591 
    592 
    593 File: bfd.info,  Node: Write Other Derived Routines,  Prev: Write the Derived Creation Routine,  Up: Deriving a New Hash Table Type
    594 
    595 Write other derived routines
     949File: bfd.info,  Node: Opening and Closing,  Next: Internal,  Prev: Architectures,  Up: BFD front end
     950
     951Opening and closing BFDs
     952========================
     953
     954`bfd_openr'
     955...........
     956
     957   *Synopsis*
     958     bfd *bfd_openr(const char *filename, const char *target);
     959   *Description*
     960Open the file FILENAME (using `fopen') with the target TARGET.  Return
     961a pointer to the created BFD.
     962
     963   Calls `bfd_find_target', so TARGET is interpreted as by that
     964function.
     965
     966   If `NULL' is returned then an error has occured.   Possible errors
     967are `bfd_error_no_memory', `bfd_error_invalid_target' or `system_call'
     968error.
     969
     970`bfd_fdopenr'
     971.............
     972
     973   *Synopsis*
     974     bfd *bfd_fdopenr(const char *filename, const char *target, int fd);
     975   *Description*
     976`bfd_fdopenr' is to `bfd_fopenr' much like `fdopen' is to `fopen'.  It
     977opens a BFD on a file already described by the FD supplied.
     978
     979   When the file is later `bfd_close'd, the file descriptor will be
     980closed.  If the caller desires that this file descriptor be cached by
     981BFD (opened as needed, closed as needed to free descriptors for other
     982opens), with the supplied FD used as an initial file descriptor (but
     983subject to closure at any time), call bfd_set_cacheable(bfd, 1) on the
     984returned BFD.  The default is to assume no cacheing; the file
     985descriptor will remain open until `bfd_close', and will not be affected
     986by BFD operations on other files.
     987
     988   Possible errors are `bfd_error_no_memory',
     989`bfd_error_invalid_target' and `bfd_error_system_call'.
     990
     991`bfd_openstreamr'
     992.................
     993
     994   *Synopsis*
     995     bfd *bfd_openstreamr(const char *, const char *, PTR);
     996   *Description*
     997Open a BFD for read access on an existing stdio stream.  When the BFD
     998is passed to `bfd_close', the stream will be closed.
     999
     1000`bfd_openw'
     1001...........
     1002
     1003   *Synopsis*
     1004     bfd *bfd_openw(const char *filename, const char *target);
     1005   *Description*
     1006Create a BFD, associated with file FILENAME, using the file format
     1007TARGET, and return a pointer to it.
     1008
     1009   Possible errors are `bfd_error_system_call', `bfd_error_no_memory',
     1010`bfd_error_invalid_target'.
     1011
     1012`bfd_close'
     1013...........
     1014
     1015   *Synopsis*
     1016     bfd_boolean bfd_close (bfd *abfd);
     1017   *Description*
     1018Close a BFD. If the BFD was open for writing, then pending operations
     1019are completed and the file written out and closed.  If the created file
     1020is executable, then `chmod' is called to mark it as such.
     1021
     1022   All memory attached to the BFD is released.
     1023
     1024   The file descriptor associated with the BFD is closed (even if it
     1025was passed in to BFD by `bfd_fdopenr').
     1026
     1027   *Returns*
     1028`TRUE' is returned if all is ok, otherwise `FALSE'.
     1029
     1030`bfd_close_all_done'
     1031....................
     1032
     1033   *Synopsis*
     1034     bfd_boolean bfd_close_all_done (bfd *);
     1035   *Description*
     1036Close a BFD.  Differs from `bfd_close' since it does not complete any
     1037pending operations.  This routine would be used if the application had
     1038just used BFD for swapping and didn't want to use any of the writing
     1039code.
     1040
     1041   If the created file is executable, then `chmod' is called to mark it
     1042as such.
     1043
     1044   All memory attached to the BFD is released.
     1045
     1046   *Returns*
     1047`TRUE' is returned if all is ok, otherwise `FALSE'.
     1048
     1049`bfd_create'
     1050............
     1051
     1052   *Synopsis*
     1053     bfd *bfd_create(const char *filename, bfd *templ);
     1054   *Description*
     1055Create a new BFD in the manner of `bfd_openw', but without opening a
     1056file. The new BFD takes the target from the target used by TEMPLATE.
     1057The format is always set to `bfd_object'.
     1058
     1059`bfd_make_writable'
     1060...................
     1061
     1062   *Synopsis*
     1063     bfd_boolean bfd_make_writable (bfd *abfd);
     1064   *Description*
     1065Takes a BFD as created by `bfd_create' and converts it into one like as
     1066returned by `bfd_openw'.  It does this by converting the BFD to
     1067BFD_IN_MEMORY.  It's assumed that you will call `bfd_make_readable' on
     1068this bfd later.
     1069
     1070   *Returns*
     1071`TRUE' is returned if all is ok, otherwise `FALSE'.
     1072
     1073`bfd_make_readable'
     1074...................
     1075
     1076   *Synopsis*
     1077     bfd_boolean bfd_make_readable (bfd *abfd);
     1078   *Description*
     1079Takes a BFD as created by `bfd_create' and `bfd_make_writable' and
     1080converts it into one like as returned by `bfd_openr'.  It does this by
     1081writing the contents out to the memory buffer, then reversing the
     1082direction.
     1083
     1084   *Returns*
     1085`TRUE' is returned if all is ok, otherwise `FALSE'.
     1086
     1087`bfd_alloc'
     1088...........
     1089
     1090   *Synopsis*
     1091     PTR bfd_alloc (bfd *abfd, size_t wanted);
     1092   *Description*
     1093Allocate a block of WANTED bytes of memory attached to `abfd' and
     1094return a pointer to it.
     1095
     1096`calc_crc32'
     1097............
     1098
     1099   *Synopsis*
     1100     unsigned long calc_crc32 (unsigned long crc, const unsigned char *buf, size_t len);
     1101   *Description*
     1102Advance the CRC32 given by CRC through LEN bytes of BUF. Return the
     1103updated CRC32 value.
     1104
     1105`get_debug_link_info'
     1106.....................
     1107
     1108   *Synopsis*
     1109     char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out)
     1110   *Description*
     1111fetch the filename and CRC32 value for any separate debuginfo
     1112associated with ABFD. Return NULL if no such info found, otherwise
     1113return filename and update CRC32_OUT.
     1114
     1115`separate_debug_file_exists'
    5961116............................
    5971117
    598    You will want to write other routines for your new hash table, as
    599 well.
    600 
    601    You will want an initialization routine which calls the
    602 initialization routine of the hash table you are deriving from and
    603 initializes any other local fields.  For the linker hash table, this is
    604 `_bfd_link_hash_table_init' in `linker.c'.
    605 
    606    You will want a lookup routine which calls the lookup routine of the
    607 hash table you are deriving from and casts the result.  The linker hash
    608 table uses `bfd_link_hash_lookup' in `linker.c' (this actually takes an
    609 additional argument which it uses to decide how to return the looked up
    610 value).
    611 
    612    You may want a traversal routine.  This should just call the
    613 traversal routine of the hash table you are deriving from with
    614 appropriate casts.  The linker hash table uses `bfd_link_hash_traverse'
    615 in `linker.c'.
    616 
    617    These routines may simply be defined as macros.  For example, the
    618 a.out backend linker hash table, which is derived from the linker hash
    619 table, uses macros for the lookup and traversal routines.  These are
    620 `aout_link_hash_lookup' and `aout_link_hash_traverse' in aoutx.h.
    621 
    622 
    623 File: bfd.info,  Node: BFD back ends,  Next: GNU Free Documentation License,  Prev: BFD front end,  Up: Top
    624 
    625 BFD back ends
    626 *************
    627 
    628 * Menu:
    629 
    630 * What to Put Where::
    631 * aout ::       a.out backends
    632 * coff ::       coff backends
    633 * elf  ::       elf backends
    634 
    635 
    636 File: bfd.info,  Node: What to Put Where,  Next: aout,  Prev: BFD back ends,  Up: BFD back ends
    637 
    638    All of BFD lives in one directory.
    639 
    640 
    641 File: bfd.info,  Node: aout,  Next: coff,  Prev: What to Put Where,  Up: BFD back ends
    642 
    643 a.out backends
    644 ==============
    645 
    646    *Description*
    647 BFD supports a number of different flavours of a.out format, though the
    648 major differences are only the sizes of the structures on disk, and the
    649 shape of the relocation information.
    650 
    651    The support is split into a basic support file `aoutx.h' and other
    652 files which derive functions from the base. One derivation file is
    653 `aoutf1.h' (for a.out flavour 1), and adds to the basic a.out functions
    654 support for sun3, sun4, 386 and 29k a.out files, to create a target
    655 jump vector for a specific target.
    656 
    657    This information is further split out into more specific files for
    658 each machine, including `sunos.c' for sun3 and sun4, `newsos3.c' for
    659 the Sony NEWS, and `demo64.c' for a demonstration of a 64 bit a.out
    660 format.
    661 
    662    The base file `aoutx.h' defines general mechanisms for reading and
    663 writing records to and from disk and various other methods which BFD
    664 requires. It is included by `aout32.c' and `aout64.c' to form the names
    665 `aout_32_swap_exec_header_in', `aout_64_swap_exec_header_in', etc.
    666 
    667    As an example, this is what goes on to make the back end for a sun4,
    668 from `aout32.c':
    669 
    670             #define ARCH_SIZE 32
    671             #include "aoutx.h"
    672 
    673    Which exports names:
    674 
    675             ...
    676             aout_32_canonicalize_reloc
    677             aout_32_find_nearest_line
    678             aout_32_get_lineno
    679             aout_32_get_reloc_upper_bound
    680             ...
    681 
    682    from `sunos.c':
    683 
    684             #define TARGET_NAME "a.out-sunos-big"
    685             #define VECNAME    sunos_big_vec
    686             #include "aoutf1.h"
    687 
    688    requires all the names from `aout32.c', and produces the jump vector
    689 
    690             sunos_big_vec
    691 
    692    The file `host-aout.c' is a special case.  It is for a large set of
    693 hosts that use "more or less standard" a.out files, and for which
    694 cross-debugging is not interesting.  It uses the standard 32-bit a.out
    695 support routines, but determines the file offsets and addresses of the
    696 text, data, and BSS sections, the machine architecture and machine
    697 type, and the entry point address, in a host-dependent manner.  Once
    698 these values have been determined, generic code is used to handle the
    699 object file.
    700 
    701    When porting it to run on a new system, you must supply:
    702 
    703              HOST_PAGE_SIZE
    704              HOST_SEGMENT_SIZE
    705              HOST_MACHINE_ARCH       (optional)
    706              HOST_MACHINE_MACHINE    (optional)
    707              HOST_TEXT_START_ADDR
    708              HOST_STACK_END_ADDR
    709 
    710    in the file `../include/sys/h-XXX.h' (for your host).  These values,
    711 plus the structures and macros defined in `a.out.h' on your host
    712 system, will produce a BFD target that will access ordinary a.out files
    713 on your host. To configure a new machine to use `host-aout.c', specify:
    714 
    715             TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec
    716             TDEPFILES= host-aout.o trad-core.o
    717 
    718    in the `config/XXX.mt' file, and modify `configure.in' to use the
    719 `XXX.mt' file (by setting "`bfd_target=XXX'") when your configuration
    720 is selected.
    721 
    722 Relocations
    723 -----------
    724 
    725    *Description*
    726 The file `aoutx.h' provides for both the _standard_ and _extended_
    727 forms of a.out relocation records.
    728 
    729    The standard records contain only an address, a symbol index, and a
    730 type field. The extended records (used on 29ks and sparcs) also have a
    731 full integer for an addend.
    732 
    733 Internal entry points
    734 ---------------------
    735 
    736    *Description*
    737 `aoutx.h' exports several routines for accessing the contents of an
    738 a.out file, which are gathered and exported in turn by various format
    739 specific files (eg sunos.c).
    740 
    741 `aout_SIZE_swap_exec_header_in'
    742 ...............................
    743 
    744    *Synopsis*
    745      void aout_SIZE_swap_exec_header_in,
    746         (bfd *abfd,
    747          struct external_exec *raw_bytes,
    748          struct internal_exec *execp);
    749    *Description*
    750 Swap the information in an executable header RAW_BYTES taken from a raw
    751 byte stream memory image into the internal exec header structure EXECP.
    752 
    753 `aout_SIZE_swap_exec_header_out'
    754 ................................
    755 
    756    *Synopsis*
    757      void aout_SIZE_swap_exec_header_out
    758         (bfd *abfd,
    759          struct internal_exec *execp,
    760          struct external_exec *raw_bytes);
    761    *Description*
    762 Swap the information in an internal exec header structure EXECP into
    763 the buffer RAW_BYTES ready for writing to disk.
    764 
    765 `aout_SIZE_some_aout_object_p'
    766 ..............................
    767 
    768    *Synopsis*
    769      const bfd_target *aout_SIZE_some_aout_object_p
    770         (bfd *abfd,
    771          const bfd_target *(*callback_to_real_object_p) ());
    772    *Description*
    773 Some a.out variant thinks that the file open in ABFD checking is an
    774 a.out file.  Do some more checking, and set up for access if it really
    775 is.  Call back to the calling environment's "finish up" function just
    776 before returning, to handle any last-minute setup.
    777 
    778 `aout_SIZE_mkobject'
    779 ....................
    780 
    781    *Synopsis*
    782      boolean aout_SIZE_mkobject, (bfd *abfd);
    783    *Description*
    784 Initialize BFD ABFD for use with a.out files.
    785 
    786 `aout_SIZE_machine_type'
    787 ........................
    788 
    789    *Synopsis*
    790      enum machine_type  aout_SIZE_machine_type
    791         (enum bfd_architecture arch,
    792          unsigned long machine));
    793    *Description*
    794 Keep track of machine architecture and machine type for a.out's. Return
    795 the `machine_type' for a particular architecture and machine, or
    796 `M_UNKNOWN' if that exact architecture and machine can't be represented
    797 in a.out format.
    798 
    799    If the architecture is understood, machine type 0 (default) is
    800 always understood.
    801 
    802 `aout_SIZE_set_arch_mach'
    803 .........................
    804 
    805    *Synopsis*
    806      boolean aout_SIZE_set_arch_mach,
    807         (bfd *,
    808          enum bfd_architecture arch,
    809          unsigned long machine));
    810    *Description*
    811 Set the architecture and the machine of the BFD ABFD to the values ARCH
    812 and MACHINE.  Verify that ABFD's format can support the architecture
    813 required.
    814 
    815 `aout_SIZE_new_section_hook'
    816 ............................
    817 
    818    *Synopsis*
    819      boolean aout_SIZE_new_section_hook,
    820         (bfd *abfd,
    821          asection *newsect));
    822    *Description*
    823 Called by the BFD in response to a `bfd_make_section' request.
    824 
     1118   *Synopsis*
     1119     bfd_boolean separate_debug_file_exists (char * name, unsigned long crc32)
     1120   *Description*
     1121Checks to see if NAME is a file and if its contents match CRC32.
     1122
     1123`find_separate_debug_file'
     1124..........................
     1125
     1126   *Synopsis*
     1127     char * find_separate_debug_file (bfd *abfd)
     1128   *Description*
     1129Searches ABFD for a reference to separate debugging information, scans
     1130various locations in the filesystem, including the file tree rooted at
     1131DEBUG_FILE_DIRECTORY, and returns a filename of such debugging
     1132information if the file is found and has matching CRC32.  Returns NULL
     1133if no reference to debugging file exists, or file cannot be found.
     1134
     1135`bfd_follow_gnu_debuglink'
     1136..........................
     1137
     1138   *Synopsis*
     1139     char * bfd_follow_gnu_debuglink(bfd *abfd, const char *dir);
     1140   *Description*
     1141Takes a BFD and searches it for a .gnu_debuglink section.  If this
     1142section is found, examines the section for the name and checksum of a
     1143'.debug' file containing auxiliary debugging information. Searches
     1144filesystem for .debug file in some standard locations, including the
     1145directory tree rooted at DIR, and if found returns the full filename.
     1146If DIR is NULL, will search default path configured into libbfd at
     1147build time.
     1148
     1149   *Returns*
     1150`NULL' on any errors or failure to locate the .debug file, otherwise a
     1151pointer to a heap-allocated string containing the filename. The caller
     1152is responsible for freeing this string.
     1153
Note: See TracChangeset for help on using the changeset viewer.