| @section @code{typedef bfd} |
| A BFD has type @code{bfd}; objects of this type are the |
| cornerstone of any application using BFD. Using BFD |
| consists of making references though the BFD and to data in the BFD. |
| |
| Here is the structure that defines the type @code{bfd}. It |
| contains the major data about the file and pointers |
| to the rest of the data. |
| |
| |
| @example |
| |
| struct _bfd |
| @{ |
| /* The filename the application opened the BFD with. */ |
| CONST char *filename; |
| |
| /* A pointer to the target jump table. */ |
| const struct bfd_target *xvec; |
| |
| /* To avoid dragging too many header files into every file that |
| includes `@code{bfd.h}', IOSTREAM has been declared as a "char |
| *", and MTIME as a "long". Their correct types, to which they |
| are cast when used, are "FILE *" and "time_t". The iostream |
| is the result of an fopen on the filename. However, if the |
| BFD_IN_MEMORY flag is set, then iostream is actually a pointer |
| to a bfd_in_memory struct. */ |
| PTR iostream; |
| |
| /* Is the file descriptor being cached? That is, can it be closed as |
| needed, and re-opened when accessed later? */ |
| |
| boolean cacheable; |
| |
| /* Marks whether there was a default target specified when the |
| BFD was opened. This is used to select which matching algorithm |
| to use to choose the back end. */ |
| |
| boolean target_defaulted; |
| |
| /* The caching routines use these to maintain a |
| least-recently-used list of BFDs */ |
| |
| struct _bfd *lru_prev, *lru_next; |
| |
| /* When a file is closed by the caching routines, BFD retains |
| state information on the file here: */ |
| |
| file_ptr where; |
| |
| /* and here: (``once'' means at least once) */ |
| |
| boolean opened_once; |
| |
| /* Set if we have a locally maintained mtime value, rather than |
| getting it from the file each time: */ |
| |
| boolean mtime_set; |
| |
| /* File modified time, if mtime_set is true: */ |
| |
| long mtime; |
| |
| /* Reserved for an unimplemented file locking extension.*/ |
| |
| int ifd; |
| |
| /* The format which belongs to the BFD. (object, core, etc.) */ |
| |
| bfd_format format; |
| |
| /* The direction the BFD was opened with*/ |
| |
| enum bfd_direction @{no_direction = 0, |
| read_direction = 1, |
| write_direction = 2, |
| both_direction = 3@} direction; |
| |
| /* Format_specific flags*/ |
| |
| flagword flags; |
| |
| /* Currently my_archive is tested before adding origin to |
| anything. I believe that this can become always an add of |
| origin, with origin set to 0 for non archive files. */ |
| |
| file_ptr origin; |
| |
| /* Remember when output has begun, to stop strange things |
| from happening. */ |
| boolean output_has_begun; |
| |
| /* Pointer to linked list of sections*/ |
| struct sec *sections; |
| |
| /* The number of sections */ |
| unsigned int section_count; |
| |
| /* Stuff only useful for object files: |
| The start address. */ |
| bfd_vma start_address; |
| |
| /* Used for input and output*/ |
| unsigned int symcount; |
| |
| /* Symbol table for output BFD (with symcount entries) */ |
| struct symbol_cache_entry **outsymbols; |
| |
| /* Pointer to structure which contains architecture information*/ |
| const struct bfd_arch_info *arch_info; |
| |
| /* Stuff only useful for archives:*/ |
| PTR arelt_data; |
| struct _bfd *my_archive; /* The containing archive BFD. */ |
| struct _bfd *next; /* The next BFD in the archive. */ |
| struct _bfd *archive_head; /* The first BFD in the archive. */ |
| boolean has_armap; |
| |
| /* A chain of BFD structures involved in a link. */ |
| struct _bfd *link_next; |
| |
| /* A field used by _bfd_generic_link_add_archive_symbols. This will |
| be used only for archive elements. */ |
| int archive_pass; |
| |
| /* Used by the back end to hold private data. */ |
| |
| union |
| @{ |
| struct aout_data_struct *aout_data; |
| struct artdata *aout_ar_data; |
| struct _oasys_data *oasys_obj_data; |
| struct _oasys_ar_data *oasys_ar_data; |
| struct coff_tdata *coff_obj_data; |
| struct pe_tdata *pe_obj_data; |
| struct xcoff_tdata *xcoff_obj_data; |
| struct ecoff_tdata *ecoff_obj_data; |
| struct ieee_data_struct *ieee_data; |
| struct ieee_ar_data_struct *ieee_ar_data; |
| struct srec_data_struct *srec_data; |
| struct ihex_data_struct *ihex_data; |
| struct tekhex_data_struct *tekhex_data; |
| struct elf_obj_tdata *elf_obj_data; |
| struct nlm_obj_tdata *nlm_obj_data; |
| struct bout_data_struct *bout_data; |
| struct sun_core_struct *sun_core_data; |
| struct sco5_core_struct *sco5_core_data; |
| struct trad_core_struct *trad_core_data; |
| struct som_data_struct *som_data; |
| struct hpux_core_struct *hpux_core_data; |
| struct hppabsd_core_struct *hppabsd_core_data; |
| struct sgi_core_struct *sgi_core_data; |
| struct lynx_core_struct *lynx_core_data; |
| struct osf_core_struct *osf_core_data; |
| struct cisco_core_struct *cisco_core_data; |
| struct versados_data_struct *versados_data; |
| struct netbsd_core_struct *netbsd_core_data; |
| PTR any; |
| @} tdata; |
| |
| /* Used by the application to hold private data*/ |
| PTR usrdata; |
| |
| /* Where all the allocated stuff under this BFD goes. This is a |
| struct objalloc *, but we use PTR to avoid requiring the inclusion of |
| objalloc.h. */ |
| PTR memory; |
| @}; |
| |
| @end example |
| @section Error reporting |
| Most BFD functions return nonzero on success (check their |
| individual documentation for precise semantics). On an error, |
| they call @code{bfd_set_error} to set an error condition that callers |
| can check by calling @code{bfd_get_error}. |
| If that returns @code{bfd_error_system_call}, then check |
| @code{errno}. |
| |
| The easiest way to report a BFD error to the user is to |
| use @code{bfd_perror}. |
| |
| @subsection Type @code{bfd_error_type} |
| The values returned by @code{bfd_get_error} are defined by the |
| enumerated type @code{bfd_error_type}. |
| |
| |
| @example |
| |
| typedef enum bfd_error |
| @{ |
| bfd_error_no_error = 0, |
| bfd_error_system_call, |
| bfd_error_invalid_target, |
| bfd_error_wrong_format, |
| bfd_error_invalid_operation, |
| bfd_error_no_memory, |
| bfd_error_no_symbols, |
| bfd_error_no_armap, |
| bfd_error_no_more_archived_files, |
| bfd_error_malformed_archive, |
| bfd_error_file_not_recognized, |
| bfd_error_file_ambiguously_recognized, |
| bfd_error_no_contents, |
| bfd_error_nonrepresentable_section, |
| bfd_error_no_debug_section, |
| bfd_error_bad_value, |
| bfd_error_file_truncated, |
| bfd_error_file_too_big, |
| bfd_error_invalid_error_code |
| @} bfd_error_type; |
| |
| @end example |
| @findex bfd_get_error |
| @subsubsection @code{bfd_get_error} |
| @strong{Synopsis} |
| @example |
| bfd_error_type bfd_get_error (void); |
| @end example |
| @strong{Description}@* |
| Return the current BFD error condition. |
| |
| @findex bfd_set_error |
| @subsubsection @code{bfd_set_error} |
| @strong{Synopsis} |
| @example |
| void bfd_set_error (bfd_error_type error_tag); |
| @end example |
| @strong{Description}@* |
| Set the BFD error condition to be @var{error_tag}. |
| |
| @findex bfd_errmsg |
| @subsubsection @code{bfd_errmsg} |
| @strong{Synopsis} |
| @example |
| CONST char *bfd_errmsg (bfd_error_type error_tag); |
| @end example |
| @strong{Description}@* |
| Return a string describing the error @var{error_tag}, or |
| the system error if @var{error_tag} is @code{bfd_error_system_call}. |
| |
| @findex bfd_perror |
| @subsubsection @code{bfd_perror} |
| @strong{Synopsis} |
| @example |
| void bfd_perror (CONST char *message); |
| @end example |
| @strong{Description}@* |
| Print to the standard error stream a string describing the |
| last BFD error that occurred, or the last system error if |
| the last BFD error was a system call failure. If @var{message} |
| is non-NULL and non-empty, the error string printed is preceded |
| by @var{message}, a colon, and a space. It is followed by a newline. |
| |
| @subsection BFD error handler |
| Some BFD functions want to print messages describing the |
| problem. They call a BFD error handler function. This |
| function may be overriden by the program. |
| |
| The BFD error handler acts like printf. |
| |
| |
| @example |
| |
| typedef void (*bfd_error_handler_type) PARAMS ((const char *, ...)); |
| |
| @end example |
| @findex bfd_set_error_handler |
| @subsubsection @code{bfd_set_error_handler} |
| @strong{Synopsis} |
| @example |
| bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type); |
| @end example |
| @strong{Description}@* |
| Set the BFD error handler function. Returns the previous |
| function. |
| |
| @findex bfd_set_error_program_name |
| @subsubsection @code{bfd_set_error_program_name} |
| @strong{Synopsis} |
| @example |
| void bfd_set_error_program_name (const char *); |
| @end example |
| @strong{Description}@* |
| Set the program name to use when printing a BFD error. This |
| is printed before the error message followed by a colon and |
| space. The string must not be changed after it is passed to |
| this function. |
| |
| @findex bfd_get_error_handler |
| @subsubsection @code{bfd_get_error_handler} |
| @strong{Synopsis} |
| @example |
| bfd_error_handler_type bfd_get_error_handler (void); |
| @end example |
| @strong{Description}@* |
| Return the BFD error handler function. |
| |
| @section Symbols |
| |
| |
| @findex bfd_get_reloc_upper_bound |
| @subsubsection @code{bfd_get_reloc_upper_bound} |
| @strong{Synopsis} |
| @example |
| long bfd_get_reloc_upper_bound(bfd *abfd, asection *sect); |
| @end example |
| @strong{Description}@* |
| Return the number of bytes required to store the |
| relocation information associated with section @var{sect} |
| attached to bfd @var{abfd}. If an error occurs, return -1. |
| |
| @findex bfd_canonicalize_reloc |
| @subsubsection @code{bfd_canonicalize_reloc} |
| @strong{Synopsis} |
| @example |
| long bfd_canonicalize_reloc |
| (bfd *abfd, |
| asection *sec, |
| arelent **loc, |
| asymbol **syms); |
| @end example |
| @strong{Description}@* |
| Call the back end associated with the open BFD |
| @var{abfd} and translate the external form of the relocation |
| information attached to @var{sec} into the internal canonical |
| form. Place the table into memory at @var{loc}, which has |
| been preallocated, usually by a call to |
| @code{bfd_get_reloc_upper_bound}. Returns the number of relocs, or |
| -1 on error. |
| |
| The @var{syms} table is also needed for horrible internal magic |
| reasons. |
| |
| @findex bfd_set_reloc |
| @subsubsection @code{bfd_set_reloc} |
| @strong{Synopsis} |
| @example |
| void bfd_set_reloc |
| (bfd *abfd, asection *sec, arelent **rel, unsigned int count) |
| @end example |
| @strong{Description}@* |
| Set the relocation pointer and count within |
| section @var{sec} to the values @var{rel} and @var{count}. |
| The argument @var{abfd} is ignored. |
| |
| @findex bfd_set_file_flags |
| @subsubsection @code{bfd_set_file_flags} |
| @strong{Synopsis} |
| @example |
| boolean bfd_set_file_flags(bfd *abfd, flagword flags); |
| @end example |
| @strong{Description}@* |
| Set the flag word in the BFD @var{abfd} to the value @var{flags}. |
| |
| Possible errors are: |
| @itemize @bullet |
| |
| @item |
| @code{bfd_error_wrong_format} - The target bfd was not of object format. |
| @item |
| @code{bfd_error_invalid_operation} - The target bfd was open for reading. |
| @item |
| @code{bfd_error_invalid_operation} - |
| The flag word contained a bit which was not applicable to the |
| type of file. E.g., an attempt was made to set the @code{D_PAGED} bit |
| on a BFD format which does not support demand paging. |
| @end itemize |
| |
| @findex bfd_get_arch_size |
| @subsubsection @code{bfd_get_arch_size} |
| @strong{Synopsis} |
| @example |
| int bfd_get_arch_size (bfd *abfd); |
| @end example |
| @strong{Description}@* |
| Returns the architecture address size, in bits, as determined |
| by the object file's format. For ELF, this information is |
| included in the header. |
| |
| @strong{Returns}@* |
| Returns the arch size in bits if known, @code{-1} otherwise. |
| |
| @findex bfd_get_sign_extend_vma |
| @subsubsection @code{bfd_get_sign_extend_vma} |
| @strong{Synopsis} |
| @example |
| int bfd_get_sign_extend_vma (bfd *abfd); |
| @end example |
| @strong{Description}@* |
| Indicates if the target architecture "naturally" sign extends |
| an address. Some architectures implicitly sign extend address |
| values when they are converted to types larger than the size |
| of an address. For instance, bfd_get_start_address() will |
| return an address sign extended to fill a bfd_vma when this is |
| the case. |
| |
| @strong{Returns}@* |
| Returns @code{1} if the target architecture is known to sign |
| extend addresses, @code{0} if the target architecture is known to |
| not sign extend addresses, and @code{-1} otherwise. |
| |
| @findex bfd_set_start_address |
| @subsubsection @code{bfd_set_start_address} |
| @strong{Synopsis} |
| @example |
| boolean bfd_set_start_address(bfd *abfd, bfd_vma vma); |
| @end example |
| @strong{Description}@* |
| Make @var{vma} the entry point of output BFD @var{abfd}. |
| |
| @strong{Returns}@* |
| Returns @code{true} on success, @code{false} otherwise. |
| |
| @findex bfd_get_mtime |
| @subsubsection @code{bfd_get_mtime} |
| @strong{Synopsis} |
| @example |
| long bfd_get_mtime(bfd *abfd); |
| @end example |
| @strong{Description}@* |
| Return the file modification time (as read from the file system, or |
| from the archive header for archive members). |
| |
| @findex bfd_get_size |
| @subsubsection @code{bfd_get_size} |
| @strong{Synopsis} |
| @example |
| long bfd_get_size(bfd *abfd); |
| @end example |
| @strong{Description}@* |
| Return the file size (as read from file system) for the file |
| associated with BFD @var{abfd}. |
| |
| The initial motivation for, and use of, this routine is not |
| so we can get the exact size of the object the BFD applies to, since |
| that might not be generally possible (archive members for example). |
| It would be ideal if someone could eventually modify |
| it so that such results were guaranteed. |
| |
| Instead, we want to ask questions like "is this NNN byte sized |
| object I'm about to try read from file offset YYY reasonable?" |
| As as example of where we might do this, some object formats |
| use string tables for which the first @code{sizeof (long)} bytes of the |
| table contain the size of the table itself, including the size bytes. |
| If an application tries to read what it thinks is one of these |
| string tables, without some way to validate the size, and for |
| some reason the size is wrong (byte swapping error, wrong location |
| for the string table, etc.), the only clue is likely to be a read |
| error when it tries to read the table, or a "virtual memory |
| exhausted" error when it tries to allocate 15 bazillon bytes |
| of space for the 15 bazillon byte table it is about to read. |
| This function at least allows us to answer the quesion, "is the |
| size reasonable?". |
| |
| @findex bfd_get_gp_size |
| @subsubsection @code{bfd_get_gp_size} |
| @strong{Synopsis} |
| @example |
| int bfd_get_gp_size(bfd *abfd); |
| @end example |
| @strong{Description}@* |
| Return the maximum size of objects to be optimized using the GP |
| register under MIPS ECOFF. This is typically set by the @code{-G} |
| argument to the compiler, assembler or linker. |
| |
| @findex bfd_set_gp_size |
| @subsubsection @code{bfd_set_gp_size} |
| @strong{Synopsis} |
| @example |
| void bfd_set_gp_size(bfd *abfd, int i); |
| @end example |
| @strong{Description}@* |
| Set the maximum size of objects to be optimized using the GP |
| register under ECOFF or MIPS ELF. This is typically set by |
| the @code{-G} argument to the compiler, assembler or linker. |
| |
| @findex bfd_scan_vma |
| @subsubsection @code{bfd_scan_vma} |
| @strong{Synopsis} |
| @example |
| bfd_vma bfd_scan_vma(CONST char *string, CONST char **end, int base); |
| @end example |
| @strong{Description}@* |
| Convert, like @code{strtoul}, a numerical expression |
| @var{string} into a @code{bfd_vma} integer, and return that integer. |
| (Though without as many bells and whistles as @code{strtoul}.) |
| The expression is assumed to be unsigned (i.e., positive). |
| If given a @var{base}, it is used as the base for conversion. |
| A base of 0 causes the function to interpret the string |
| in hex if a leading "0x" or "0X" is found, otherwise |
| in octal if a leading zero is found, otherwise in decimal. |
| |
| Overflow is not detected. |
| |
| @findex bfd_copy_private_bfd_data |
| @subsubsection @code{bfd_copy_private_bfd_data} |
| @strong{Synopsis} |
| @example |
| boolean bfd_copy_private_bfd_data(bfd *ibfd, bfd *obfd); |
| @end example |
| @strong{Description}@* |
| Copy private BFD information from the BFD @var{ibfd} to the |
| the BFD @var{obfd}. Return @code{true} on success, @code{false} on error. |
| Possible error returns are: |
| |
| @itemize @bullet |
| |
| @item |
| @code{bfd_error_no_memory} - |
| Not enough memory exists to create private data for @var{obfd}. |
| @end itemize |
| @example |
| #define bfd_copy_private_bfd_data(ibfd, obfd) \ |
| BFD_SEND (obfd, _bfd_copy_private_bfd_data, \ |
| (ibfd, obfd)) |
| @end example |
| |
| @findex bfd_merge_private_bfd_data |
| @subsubsection @code{bfd_merge_private_bfd_data} |
| @strong{Synopsis} |
| @example |
| boolean bfd_merge_private_bfd_data(bfd *ibfd, bfd *obfd); |
| @end example |
| @strong{Description}@* |
| Merge private BFD information from the BFD @var{ibfd} to the |
| the output file BFD @var{obfd} when linking. Return @code{true} |
| on success, @code{false} on error. Possible error returns are: |
| |
| @itemize @bullet |
| |
| @item |
| @code{bfd_error_no_memory} - |
| Not enough memory exists to create private data for @var{obfd}. |
| @end itemize |
| @example |
| #define bfd_merge_private_bfd_data(ibfd, obfd) \ |
| BFD_SEND (obfd, _bfd_merge_private_bfd_data, \ |
| (ibfd, obfd)) |
| @end example |
| |
| @findex bfd_set_private_flags |
| @subsubsection @code{bfd_set_private_flags} |
| @strong{Synopsis} |
| @example |
| boolean bfd_set_private_flags(bfd *abfd, flagword flags); |
| @end example |
| @strong{Description}@* |
| Set private BFD flag information in the BFD @var{abfd}. |
| Return @code{true} on success, @code{false} on error. Possible error |
| returns are: |
| |
| @itemize @bullet |
| |
| @item |
| @code{bfd_error_no_memory} - |
| Not enough memory exists to create private data for @var{obfd}. |
| @end itemize |
| @example |
| #define bfd_set_private_flags(abfd, flags) \ |
| BFD_SEND (abfd, _bfd_set_private_flags, \ |
| (abfd, flags)) |
| @end example |
| |
| @findex stuff |
| @subsubsection @code{stuff} |
| @strong{Description}@* |
| Stuff which should be documented: |
| @example |
| #define bfd_sizeof_headers(abfd, reloc) \ |
| BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc)) |
| |
| #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \ |
| BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, sec, syms, off, file, func, line)) |
| |
| /* Do these three do anything useful at all, for any back end? */ |
| #define bfd_debug_info_start(abfd) \ |
| BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) |
| |
| #define bfd_debug_info_end(abfd) \ |
| BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) |
| |
| #define bfd_debug_info_accumulate(abfd, section) \ |
| BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) |
| |
| |
| #define bfd_stat_arch_elt(abfd, stat) \ |
| BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat)) |
| |
| #define bfd_update_armap_timestamp(abfd) \ |
| BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd)) |
| |
| #define bfd_set_arch_mach(abfd, arch, mach)\ |
| BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) |
| |
| #define bfd_relax_section(abfd, section, link_info, again) \ |
| BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again)) |
| |
| #define bfd_gc_sections(abfd, link_info) \ |
| BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info)) |
| |
| #define bfd_link_hash_table_create(abfd) \ |
| BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd)) |
| |
| #define bfd_link_add_symbols(abfd, info) \ |
| BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info)) |
| |
| #define bfd_final_link(abfd, info) \ |
| BFD_SEND (abfd, _bfd_final_link, (abfd, info)) |
| |
| #define bfd_free_cached_info(abfd) \ |
| BFD_SEND (abfd, _bfd_free_cached_info, (abfd)) |
| |
| #define bfd_get_dynamic_symtab_upper_bound(abfd) \ |
| BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd)) |
| |
| #define bfd_print_private_bfd_data(abfd, file)\ |
| BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file)) |
| |
| #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \ |
| BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols)) |
| |
| #define bfd_get_dynamic_reloc_upper_bound(abfd) \ |
| BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd)) |
| |
| #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \ |
| BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms)) |
| |
| extern bfd_byte *bfd_get_relocated_section_contents |
| PARAMS ((bfd *, struct bfd_link_info *, |
| struct bfd_link_order *, bfd_byte *, |
| boolean, asymbol **)); |
| |
| @end example |
| |