diff options
Diffstat (limited to 'contrib/binutils/bfd/doc/bfdt.texi')
| -rw-r--r-- | contrib/binutils/bfd/doc/bfdt.texi | 690 |
1 files changed, 0 insertions, 690 deletions
diff --git a/contrib/binutils/bfd/doc/bfdt.texi b/contrib/binutils/bfd/doc/bfdt.texi deleted file mode 100644 index 74cace4a60a5..000000000000 --- a/contrib/binutils/bfd/doc/bfdt.texi +++ /dev/null @@ -1,690 +0,0 @@ -@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 -@{ - /* A unique identifier of the BFD */ - unsigned int id; - - /* 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. */ - void *iostream; - - /* Is the file descriptor being cached? That is, can it be closed as - needed, and re-opened when accessed later? */ - bfd_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. */ - bfd_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... */ - ufile_ptr where; - - /* ... and here: (``once'' means at least once). */ - bfd_boolean opened_once; - - /* Set if we have a locally maintained mtime value, rather than - getting it from the file each time. */ - bfd_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 with which the BFD was opened. */ - 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. */ - ufile_ptr origin; - - /* Remember when output has begun, to stop strange things - from happening. */ - bfd_boolean output_has_begun; - - /* A hash table for section names. */ - struct bfd_hash_table section_htab; - - /* Pointer to linked list of sections. */ - struct bfd_section *sections; - - /* The place where we add to the section list. */ - struct bfd_section **section_tail; - - /* 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 bfd_symbol **outsymbols; - - /* Used for slurped dynamic symbol tables. */ - unsigned int dynsymcount; - - /* Pointer to structure which contains architecture information. */ - const struct bfd_arch_info *arch_info; - - /* Stuff only useful for archives. */ - void *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. */ - bfd_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 mmo_data_struct *mmo_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; - struct mach_o_data_struct *mach_o_data; - struct mach_o_fat_data_struct *mach_o_fat_data; - struct bfd_pef_data_struct *pef_data; - struct bfd_pef_xlib_data_struct *pef_xlib_data; - struct bfd_sym_data_struct *sym_data; - void *any; - @} - tdata; - - /* Used by the application to hold private data. */ - void *usrdata; - - /* Where all the allocated stuff under this BFD goes. This is a - struct objalloc *, but we use void * to avoid requiring the inclusion - of objalloc.h. */ - void *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_wrong_object_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 overridden by the program. - -The BFD error handler acts like printf. - - -@example - -typedef void (*bfd_error_handler_type) (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. - -@findex bfd_archive_filename -@subsubsection @code{bfd_archive_filename} -@strong{Synopsis} -@example -const char *bfd_archive_filename (bfd *); -@end example -@strong{Description}@* -For a BFD that is a component of an archive, returns a string -with both the archive name and file name. For other BFDs, just -returns the file name. - -@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 -bfd_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 -bfd_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_gp_size -@subsubsection @code{bfd_get_gp_size} -@strong{Synopsis} -@example -unsigned 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, unsigned 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. - -If the value would overflow, the maximum @code{bfd_vma} value is -returned. - -@findex bfd_copy_private_bfd_data -@subsubsection @code{bfd_copy_private_bfd_data} -@strong{Synopsis} -@example -bfd_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 -bfd_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 -bfd_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 Other functions -@subsubsection @code{Other functions} -@strong{Description}@* -The following functions exist but have not yet been 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)) - -#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_merge_sections(abfd, link_info) \ - BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info)) - -#define bfd_discard_group(abfd, sec) \ - BFD_SEND (abfd, _bfd_discard_group, (abfd, sec)) - -#define bfd_link_hash_table_create(abfd) \ - BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd)) - -#define bfd_link_hash_table_free(abfd, hash) \ - BFD_SEND (abfd, _bfd_link_hash_table_free, (hash)) - -#define bfd_link_add_symbols(abfd, info) \ - BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info)) - -#define bfd_link_just_syms(sec, info) \ - BFD_SEND (abfd, _bfd_link_just_syms, (sec, 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 - (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *, - bfd_boolean, asymbol **); - -@end example - -@findex bfd_alt_mach_code -@subsubsection @code{bfd_alt_mach_code} -@strong{Synopsis} -@example -bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative); -@end example -@strong{Description}@* -When more than one machine code number is available for the -same machine type, this function can be used to switch between -the preferred one (alternative == 0) and any others. Currently, -only ELF supports this feature, with up to two alternate -machine codes. - - -@example -struct bfd_preserve -@{ - void *marker; - void *tdata; - flagword flags; - const struct bfd_arch_info *arch_info; - struct bfd_section *sections; - struct bfd_section **section_tail; - unsigned int section_count; - struct bfd_hash_table section_htab; -@}; - -@end example -@findex bfd_preserve_save -@subsubsection @code{bfd_preserve_save} -@strong{Synopsis} -@example -bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *); -@end example -@strong{Description}@* -When testing an object for compatibility with a particular -target back-end, the back-end object_p function needs to set -up certain fields in the bfd on successfully recognizing the -object. This typically happens in a piecemeal fashion, with -failures possible at many points. On failure, the bfd is -supposed to be restored to its initial state, which is -virtually impossible. However, restoring a subset of the bfd -state works in practice. This function stores the subset and -reinitializes the bfd. - -@findex bfd_preserve_restore -@subsubsection @code{bfd_preserve_restore} -@strong{Synopsis} -@example -void bfd_preserve_restore (bfd *, struct bfd_preserve *); -@end example -@strong{Description}@* -This function restores bfd state saved by bfd_preserve_save. -If MARKER is non-NULL in struct bfd_preserve then that block -and all subsequently bfd_alloc'd memory is freed. - -@findex bfd_preserve_finish -@subsubsection @code{bfd_preserve_finish} -@strong{Synopsis} -@example -void bfd_preserve_finish (bfd *, struct bfd_preserve *); -@end example -@strong{Description}@* -This function should be called when the bfd state saved by -bfd_preserve_save is no longer needed. ie. when the back-end -object_p function returns with success. - |