bfdt.texi revision 1.2
1@section @code{typedef bfd} 2A BFD has type @code{bfd}; objects of this type are the 3cornerstone of any application using BFD. Using BFD 4consists of making references though the BFD and to data in the BFD. 5 6Here is the structure that defines the type @code{bfd}. It 7contains the major data about the file and pointers 8to the rest of the data. 9 10 11@example 12 13struct bfd 14@{ 15 /* A unique identifier of the BFD */ 16 unsigned int id; 17 18 /* The filename the application opened the BFD with. */ 19 const char *filename; 20 21 /* A pointer to the target jump table. */ 22 const struct bfd_target *xvec; 23 24 /* The IOSTREAM, and corresponding IO vector that provide access 25 to the file backing the BFD. */ 26 void *iostream; 27 const struct bfd_iovec *iovec; 28 29 /* The caching routines use these to maintain a 30 least-recently-used list of BFDs. */ 31 struct bfd *lru_prev, *lru_next; 32 33 /* When a file is closed by the caching routines, BFD retains 34 state information on the file here... */ 35 ufile_ptr where; 36 37 /* File modified time, if mtime_set is TRUE. */ 38 long mtime; 39 40 /* Reserved for an unimplemented file locking extension. */ 41 int ifd; 42 43 /* The format which belongs to the BFD. (object, core, etc.) */ 44 bfd_format format; 45 46 /* The direction with which the BFD was opened. */ 47 enum bfd_direction 48 @{ 49 no_direction = 0, 50 read_direction = 1, 51 write_direction = 2, 52 both_direction = 3 53 @} 54 direction; 55 56 /* Format_specific flags. */ 57 flagword flags; 58 59 /* Values that may appear in the flags field of a BFD. These also 60 appear in the object_flags field of the bfd_target structure, where 61 they indicate the set of flags used by that backend (not all flags 62 are meaningful for all object file formats) (FIXME: at the moment, 63 the object_flags values have mostly just been copied from backend 64 to another, and are not necessarily correct). */ 65 66#define BFD_NO_FLAGS 0x00 67 68 /* BFD contains relocation entries. */ 69#define HAS_RELOC 0x01 70 71 /* BFD is directly executable. */ 72#define EXEC_P 0x02 73 74 /* BFD has line number information (basically used for F_LNNO in a 75 COFF header). */ 76#define HAS_LINENO 0x04 77 78 /* BFD has debugging information. */ 79#define HAS_DEBUG 0x08 80 81 /* BFD has symbols. */ 82#define HAS_SYMS 0x10 83 84 /* BFD has local symbols (basically used for F_LSYMS in a COFF 85 header). */ 86#define HAS_LOCALS 0x20 87 88 /* BFD is a dynamic object. */ 89#define DYNAMIC 0x40 90 91 /* Text section is write protected (if D_PAGED is not set, this is 92 like an a.out NMAGIC file) (the linker sets this by default, but 93 clears it for -r or -N). */ 94#define WP_TEXT 0x80 95 96 /* BFD is dynamically paged (this is like an a.out ZMAGIC file) (the 97 linker sets this by default, but clears it for -r or -n or -N). */ 98#define D_PAGED 0x100 99 100 /* BFD is relaxable (this means that bfd_relax_section may be able to 101 do something) (sometimes bfd_relax_section can do something even if 102 this is not set). */ 103#define BFD_IS_RELAXABLE 0x200 104 105 /* This may be set before writing out a BFD to request using a 106 traditional format. For example, this is used to request that when 107 writing out an a.out object the symbols not be hashed to eliminate 108 duplicates. */ 109#define BFD_TRADITIONAL_FORMAT 0x400 110 111 /* This flag indicates that the BFD contents are actually cached 112 in memory. If this is set, iostream points to a bfd_in_memory 113 struct. */ 114#define BFD_IN_MEMORY 0x800 115 116 /* The sections in this BFD specify a memory page. */ 117#define HAS_LOAD_PAGE 0x1000 118 119 /* This BFD has been created by the linker and doesn't correspond 120 to any input file. */ 121#define BFD_LINKER_CREATED 0x2000 122 123/* This may be set before writing out a BFD to request that it 124 be written using values for UIDs, GIDs, timestamps, etc. that 125 will be consistent from run to run. */ 126#define BFD_DETERMINISTIC_OUTPUT 0x4000 127 128 /* Currently my_archive is tested before adding origin to 129 anything. I believe that this can become always an add of 130 origin, with origin set to 0 for non archive files. */ 131 ufile_ptr origin; 132 133 /* The origin in the archive of the proxy entry. This will 134 normally be the same as origin, except for thin archives, 135 when it will contain the current offset of the proxy in the 136 thin archive rather than the offset of the bfd in its actual 137 container. */ 138 ufile_ptr proxy_origin; 139 140 /* A hash table for section names. */ 141 struct bfd_hash_table section_htab; 142 143 /* Pointer to linked list of sections. */ 144 struct bfd_section *sections; 145 146 /* The last section on the section list. */ 147 struct bfd_section *section_last; 148 149 /* The number of sections. */ 150 unsigned int section_count; 151 152 /* Stuff only useful for object files: 153 The start address. */ 154 bfd_vma start_address; 155 156 /* Used for input and output. */ 157 unsigned int symcount; 158 159 /* Symbol table for output BFD (with symcount entries). 160 Also used by the linker to cache input BFD symbols. */ 161 struct bfd_symbol **outsymbols; 162 163 /* Used for slurped dynamic symbol tables. */ 164 unsigned int dynsymcount; 165 166 /* Pointer to structure which contains architecture information. */ 167 const struct bfd_arch_info *arch_info; 168 169 /* Stuff only useful for archives. */ 170 void *arelt_data; 171 struct bfd *my_archive; /* The containing archive BFD. */ 172 struct bfd *archive_next; /* The next BFD in the archive. */ 173 struct bfd *archive_head; /* The first BFD in the archive. */ 174 struct bfd *nested_archives; /* List of nested archive in a flattened 175 thin archive. */ 176 177 /* A chain of BFD structures involved in a link. */ 178 struct bfd *link_next; 179 180 /* A field used by _bfd_generic_link_add_archive_symbols. This will 181 be used only for archive elements. */ 182 int archive_pass; 183 184 /* Used by the back end to hold private data. */ 185 union 186 @{ 187 struct aout_data_struct *aout_data; 188 struct artdata *aout_ar_data; 189 struct _oasys_data *oasys_obj_data; 190 struct _oasys_ar_data *oasys_ar_data; 191 struct coff_tdata *coff_obj_data; 192 struct pe_tdata *pe_obj_data; 193 struct xcoff_tdata *xcoff_obj_data; 194 struct ecoff_tdata *ecoff_obj_data; 195 struct ieee_data_struct *ieee_data; 196 struct ieee_ar_data_struct *ieee_ar_data; 197 struct srec_data_struct *srec_data; 198 struct ihex_data_struct *ihex_data; 199 struct tekhex_data_struct *tekhex_data; 200 struct elf_obj_tdata *elf_obj_data; 201 struct nlm_obj_tdata *nlm_obj_data; 202 struct bout_data_struct *bout_data; 203 struct mmo_data_struct *mmo_data; 204 struct sun_core_struct *sun_core_data; 205 struct sco5_core_struct *sco5_core_data; 206 struct trad_core_struct *trad_core_data; 207 struct som_data_struct *som_data; 208 struct hpux_core_struct *hpux_core_data; 209 struct hppabsd_core_struct *hppabsd_core_data; 210 struct sgi_core_struct *sgi_core_data; 211 struct lynx_core_struct *lynx_core_data; 212 struct osf_core_struct *osf_core_data; 213 struct cisco_core_struct *cisco_core_data; 214 struct versados_data_struct *versados_data; 215 struct netbsd_core_struct *netbsd_core_data; 216 struct mach_o_data_struct *mach_o_data; 217 struct mach_o_fat_data_struct *mach_o_fat_data; 218 struct bfd_pef_data_struct *pef_data; 219 struct bfd_pef_xlib_data_struct *pef_xlib_data; 220 struct bfd_sym_data_struct *sym_data; 221 void *any; 222 @} 223 tdata; 224 225 /* Used by the application to hold private data. */ 226 void *usrdata; 227 228 /* Where all the allocated stuff under this BFD goes. This is a 229 struct objalloc *, but we use void * to avoid requiring the inclusion 230 of objalloc.h. */ 231 void *memory; 232 233 /* Is the file descriptor being cached? That is, can it be closed as 234 needed, and re-opened when accessed later? */ 235 unsigned int cacheable : 1; 236 237 /* Marks whether there was a default target specified when the 238 BFD was opened. This is used to select which matching algorithm 239 to use to choose the back end. */ 240 unsigned int target_defaulted : 1; 241 242 /* ... and here: (``once'' means at least once). */ 243 unsigned int opened_once : 1; 244 245 /* Set if we have a locally maintained mtime value, rather than 246 getting it from the file each time. */ 247 unsigned int mtime_set : 1; 248 249 /* Flag set if symbols from this BFD should not be exported. */ 250 unsigned int no_export : 1; 251 252 /* Remember when output has begun, to stop strange things 253 from happening. */ 254 unsigned int output_has_begun : 1; 255 256 /* Have archive map. */ 257 unsigned int has_armap : 1; 258 259 /* Set if this is a thin archive. */ 260 unsigned int is_thin_archive : 1; 261@}; 262 263@end example 264@section Error reporting 265Most BFD functions return nonzero on success (check their 266individual documentation for precise semantics). On an error, 267they call @code{bfd_set_error} to set an error condition that callers 268can check by calling @code{bfd_get_error}. 269If that returns @code{bfd_error_system_call}, then check 270@code{errno}. 271 272The easiest way to report a BFD error to the user is to 273use @code{bfd_perror}. 274 275@subsection Type @code{bfd_error_type} 276The values returned by @code{bfd_get_error} are defined by the 277enumerated type @code{bfd_error_type}. 278 279 280@example 281 282typedef enum bfd_error 283@{ 284 bfd_error_no_error = 0, 285 bfd_error_system_call, 286 bfd_error_invalid_target, 287 bfd_error_wrong_format, 288 bfd_error_wrong_object_format, 289 bfd_error_invalid_operation, 290 bfd_error_no_memory, 291 bfd_error_no_symbols, 292 bfd_error_no_armap, 293 bfd_error_no_more_archived_files, 294 bfd_error_malformed_archive, 295 bfd_error_file_not_recognized, 296 bfd_error_file_ambiguously_recognized, 297 bfd_error_no_contents, 298 bfd_error_nonrepresentable_section, 299 bfd_error_no_debug_section, 300 bfd_error_bad_value, 301 bfd_error_file_truncated, 302 bfd_error_file_too_big, 303 bfd_error_on_input, 304 bfd_error_invalid_error_code 305@} 306bfd_error_type; 307 308@end example 309@findex bfd_get_error 310@subsubsection @code{bfd_get_error} 311@strong{Synopsis} 312@example 313bfd_error_type bfd_get_error (void); 314@end example 315@strong{Description}@* 316Return the current BFD error condition. 317 318@findex bfd_set_error 319@subsubsection @code{bfd_set_error} 320@strong{Synopsis} 321@example 322void bfd_set_error (bfd_error_type error_tag, ...); 323@end example 324@strong{Description}@* 325Set the BFD error condition to be @var{error_tag}. 326If @var{error_tag} is bfd_error_on_input, then this function 327takes two more parameters, the input bfd where the error 328occurred, and the bfd_error_type error. 329 330@findex bfd_errmsg 331@subsubsection @code{bfd_errmsg} 332@strong{Synopsis} 333@example 334const char *bfd_errmsg (bfd_error_type error_tag); 335@end example 336@strong{Description}@* 337Return a string describing the error @var{error_tag}, or 338the system error if @var{error_tag} is @code{bfd_error_system_call}. 339 340@findex bfd_perror 341@subsubsection @code{bfd_perror} 342@strong{Synopsis} 343@example 344void bfd_perror (const char *message); 345@end example 346@strong{Description}@* 347Print to the standard error stream a string describing the 348last BFD error that occurred, or the last system error if 349the last BFD error was a system call failure. If @var{message} 350is non-NULL and non-empty, the error string printed is preceded 351by @var{message}, a colon, and a space. It is followed by a newline. 352 353@subsection BFD error handler 354Some BFD functions want to print messages describing the 355problem. They call a BFD error handler function. This 356function may be overridden by the program. 357 358The BFD error handler acts like printf. 359 360 361@example 362 363typedef void (*bfd_error_handler_type) (const char *, ...); 364 365@end example 366@findex bfd_set_error_handler 367@subsubsection @code{bfd_set_error_handler} 368@strong{Synopsis} 369@example 370bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type); 371@end example 372@strong{Description}@* 373Set the BFD error handler function. Returns the previous 374function. 375 376@findex bfd_set_error_program_name 377@subsubsection @code{bfd_set_error_program_name} 378@strong{Synopsis} 379@example 380void bfd_set_error_program_name (const char *); 381@end example 382@strong{Description}@* 383Set the program name to use when printing a BFD error. This 384is printed before the error message followed by a colon and 385space. The string must not be changed after it is passed to 386this function. 387 388@findex bfd_get_error_handler 389@subsubsection @code{bfd_get_error_handler} 390@strong{Synopsis} 391@example 392bfd_error_handler_type bfd_get_error_handler (void); 393@end example 394@strong{Description}@* 395Return the BFD error handler function. 396 397@section Miscellaneous 398 399 400@subsection Miscellaneous functions 401 402 403@findex bfd_get_reloc_upper_bound 404@subsubsection @code{bfd_get_reloc_upper_bound} 405@strong{Synopsis} 406@example 407long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect); 408@end example 409@strong{Description}@* 410Return the number of bytes required to store the 411relocation information associated with section @var{sect} 412attached to bfd @var{abfd}. If an error occurs, return -1. 413 414@findex bfd_canonicalize_reloc 415@subsubsection @code{bfd_canonicalize_reloc} 416@strong{Synopsis} 417@example 418long bfd_canonicalize_reloc 419 (bfd *abfd, asection *sec, arelent **loc, asymbol **syms); 420@end example 421@strong{Description}@* 422Call the back end associated with the open BFD 423@var{abfd} and translate the external form of the relocation 424information attached to @var{sec} into the internal canonical 425form. Place the table into memory at @var{loc}, which has 426been preallocated, usually by a call to 427@code{bfd_get_reloc_upper_bound}. Returns the number of relocs, or 428-1 on error. 429 430The @var{syms} table is also needed for horrible internal magic 431reasons. 432 433@findex bfd_set_reloc 434@subsubsection @code{bfd_set_reloc} 435@strong{Synopsis} 436@example 437void bfd_set_reloc 438 (bfd *abfd, asection *sec, arelent **rel, unsigned int count); 439@end example 440@strong{Description}@* 441Set the relocation pointer and count within 442section @var{sec} to the values @var{rel} and @var{count}. 443The argument @var{abfd} is ignored. 444 445@findex bfd_set_file_flags 446@subsubsection @code{bfd_set_file_flags} 447@strong{Synopsis} 448@example 449bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags); 450@end example 451@strong{Description}@* 452Set the flag word in the BFD @var{abfd} to the value @var{flags}. 453 454Possible errors are: 455@itemize @bullet 456 457@item 458@code{bfd_error_wrong_format} - The target bfd was not of object format. 459@item 460@code{bfd_error_invalid_operation} - The target bfd was open for reading. 461@item 462@code{bfd_error_invalid_operation} - 463The flag word contained a bit which was not applicable to the 464type of file. E.g., an attempt was made to set the @code{D_PAGED} bit 465on a BFD format which does not support demand paging. 466@end itemize 467 468@findex bfd_get_arch_size 469@subsubsection @code{bfd_get_arch_size} 470@strong{Synopsis} 471@example 472int bfd_get_arch_size (bfd *abfd); 473@end example 474@strong{Description}@* 475Returns the architecture address size, in bits, as determined 476by the object file's format. For ELF, this information is 477included in the header. 478 479@strong{Returns}@* 480Returns the arch size in bits if known, @code{-1} otherwise. 481 482@findex bfd_get_sign_extend_vma 483@subsubsection @code{bfd_get_sign_extend_vma} 484@strong{Synopsis} 485@example 486int bfd_get_sign_extend_vma (bfd *abfd); 487@end example 488@strong{Description}@* 489Indicates if the target architecture "naturally" sign extends 490an address. Some architectures implicitly sign extend address 491values when they are converted to types larger than the size 492of an address. For instance, bfd_get_start_address() will 493return an address sign extended to fill a bfd_vma when this is 494the case. 495 496@strong{Returns}@* 497Returns @code{1} if the target architecture is known to sign 498extend addresses, @code{0} if the target architecture is known to 499not sign extend addresses, and @code{-1} otherwise. 500 501@findex bfd_set_start_address 502@subsubsection @code{bfd_set_start_address} 503@strong{Synopsis} 504@example 505bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma); 506@end example 507@strong{Description}@* 508Make @var{vma} the entry point of output BFD @var{abfd}. 509 510@strong{Returns}@* 511Returns @code{TRUE} on success, @code{FALSE} otherwise. 512 513@findex bfd_get_gp_size 514@subsubsection @code{bfd_get_gp_size} 515@strong{Synopsis} 516@example 517unsigned int bfd_get_gp_size (bfd *abfd); 518@end example 519@strong{Description}@* 520Return the maximum size of objects to be optimized using the GP 521register under MIPS ECOFF. This is typically set by the @code{-G} 522argument to the compiler, assembler or linker. 523 524@findex bfd_set_gp_size 525@subsubsection @code{bfd_set_gp_size} 526@strong{Synopsis} 527@example 528void bfd_set_gp_size (bfd *abfd, unsigned int i); 529@end example 530@strong{Description}@* 531Set the maximum size of objects to be optimized using the GP 532register under ECOFF or MIPS ELF. This is typically set by 533the @code{-G} argument to the compiler, assembler or linker. 534 535@findex bfd_scan_vma 536@subsubsection @code{bfd_scan_vma} 537@strong{Synopsis} 538@example 539bfd_vma bfd_scan_vma (const char *string, const char **end, int base); 540@end example 541@strong{Description}@* 542Convert, like @code{strtoul}, a numerical expression 543@var{string} into a @code{bfd_vma} integer, and return that integer. 544(Though without as many bells and whistles as @code{strtoul}.) 545The expression is assumed to be unsigned (i.e., positive). 546If given a @var{base}, it is used as the base for conversion. 547A base of 0 causes the function to interpret the string 548in hex if a leading "0x" or "0X" is found, otherwise 549in octal if a leading zero is found, otherwise in decimal. 550 551If the value would overflow, the maximum @code{bfd_vma} value is 552returned. 553 554@findex bfd_copy_private_header_data 555@subsubsection @code{bfd_copy_private_header_data} 556@strong{Synopsis} 557@example 558bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd); 559@end example 560@strong{Description}@* 561Copy private BFD header information from the BFD @var{ibfd} to the 562the BFD @var{obfd}. This copies information that may require 563sections to exist, but does not require symbol tables. Return 564@code{true} on success, @code{false} on error. 565Possible error returns are: 566 567@itemize @bullet 568 569@item 570@code{bfd_error_no_memory} - 571Not enough memory exists to create private data for @var{obfd}. 572@end itemize 573@example 574#define bfd_copy_private_header_data(ibfd, obfd) \ 575 BFD_SEND (obfd, _bfd_copy_private_header_data, \ 576 (ibfd, obfd)) 577@end example 578 579@findex bfd_copy_private_bfd_data 580@subsubsection @code{bfd_copy_private_bfd_data} 581@strong{Synopsis} 582@example 583bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd); 584@end example 585@strong{Description}@* 586Copy private BFD information from the BFD @var{ibfd} to the 587the BFD @var{obfd}. Return @code{TRUE} on success, @code{FALSE} on error. 588Possible error returns are: 589 590@itemize @bullet 591 592@item 593@code{bfd_error_no_memory} - 594Not enough memory exists to create private data for @var{obfd}. 595@end itemize 596@example 597#define bfd_copy_private_bfd_data(ibfd, obfd) \ 598 BFD_SEND (obfd, _bfd_copy_private_bfd_data, \ 599 (ibfd, obfd)) 600@end example 601 602@findex bfd_merge_private_bfd_data 603@subsubsection @code{bfd_merge_private_bfd_data} 604@strong{Synopsis} 605@example 606bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd); 607@end example 608@strong{Description}@* 609Merge private BFD information from the BFD @var{ibfd} to the 610the output file BFD @var{obfd} when linking. Return @code{TRUE} 611on success, @code{FALSE} on error. Possible error returns are: 612 613@itemize @bullet 614 615@item 616@code{bfd_error_no_memory} - 617Not enough memory exists to create private data for @var{obfd}. 618@end itemize 619@example 620#define bfd_merge_private_bfd_data(ibfd, obfd) \ 621 BFD_SEND (obfd, _bfd_merge_private_bfd_data, \ 622 (ibfd, obfd)) 623@end example 624 625@findex bfd_set_private_flags 626@subsubsection @code{bfd_set_private_flags} 627@strong{Synopsis} 628@example 629bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags); 630@end example 631@strong{Description}@* 632Set private BFD flag information in the BFD @var{abfd}. 633Return @code{TRUE} on success, @code{FALSE} on error. Possible error 634returns are: 635 636@itemize @bullet 637 638@item 639@code{bfd_error_no_memory} - 640Not enough memory exists to create private data for @var{obfd}. 641@end itemize 642@example 643#define bfd_set_private_flags(abfd, flags) \ 644 BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags)) 645@end example 646 647@findex Other functions 648@subsubsection @code{Other functions} 649@strong{Description}@* 650The following functions exist but have not yet been documented. 651@example 652#define bfd_sizeof_headers(abfd, info) \ 653 BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info)) 654 655#define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \ 656 BFD_SEND (abfd, _bfd_find_nearest_line, \ 657 (abfd, sec, syms, off, file, func, line)) 658 659#define bfd_find_line(abfd, syms, sym, file, line) \ 660 BFD_SEND (abfd, _bfd_find_line, \ 661 (abfd, syms, sym, file, line)) 662 663#define bfd_find_inliner_info(abfd, file, func, line) \ 664 BFD_SEND (abfd, _bfd_find_inliner_info, \ 665 (abfd, file, func, line)) 666 667#define bfd_debug_info_start(abfd) \ 668 BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) 669 670#define bfd_debug_info_end(abfd) \ 671 BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) 672 673#define bfd_debug_info_accumulate(abfd, section) \ 674 BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) 675 676#define bfd_stat_arch_elt(abfd, stat) \ 677 BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat)) 678 679#define bfd_update_armap_timestamp(abfd) \ 680 BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd)) 681 682#define bfd_set_arch_mach(abfd, arch, mach)\ 683 BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) 684 685#define bfd_relax_section(abfd, section, link_info, again) \ 686 BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again)) 687 688#define bfd_gc_sections(abfd, link_info) \ 689 BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info)) 690 691#define bfd_merge_sections(abfd, link_info) \ 692 BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info)) 693 694#define bfd_is_group_section(abfd, sec) \ 695 BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec)) 696 697#define bfd_discard_group(abfd, sec) \ 698 BFD_SEND (abfd, _bfd_discard_group, (abfd, sec)) 699 700#define bfd_link_hash_table_create(abfd) \ 701 BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd)) 702 703#define bfd_link_hash_table_free(abfd, hash) \ 704 BFD_SEND (abfd, _bfd_link_hash_table_free, (hash)) 705 706#define bfd_link_add_symbols(abfd, info) \ 707 BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info)) 708 709#define bfd_link_just_syms(abfd, sec, info) \ 710 BFD_SEND (abfd, _bfd_link_just_syms, (sec, info)) 711 712#define bfd_final_link(abfd, info) \ 713 BFD_SEND (abfd, _bfd_final_link, (abfd, info)) 714 715#define bfd_free_cached_info(abfd) \ 716 BFD_SEND (abfd, _bfd_free_cached_info, (abfd)) 717 718#define bfd_get_dynamic_symtab_upper_bound(abfd) \ 719 BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd)) 720 721#define bfd_print_private_bfd_data(abfd, file)\ 722 BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file)) 723 724#define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \ 725 BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols)) 726 727#define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \ 728 BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \ 729 dyncount, dynsyms, ret)) 730 731#define bfd_get_dynamic_reloc_upper_bound(abfd) \ 732 BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd)) 733 734#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \ 735 BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms)) 736 737extern bfd_byte *bfd_get_relocated_section_contents 738 (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *, 739 bfd_boolean, asymbol **); 740 741@end example 742 743@findex bfd_alt_mach_code 744@subsubsection @code{bfd_alt_mach_code} 745@strong{Synopsis} 746@example 747bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative); 748@end example 749@strong{Description}@* 750When more than one machine code number is available for the 751same machine type, this function can be used to switch between 752the preferred one (alternative == 0) and any others. Currently, 753only ELF supports this feature, with up to two alternate 754machine codes. 755 756 757@example 758struct bfd_preserve 759@{ 760 void *marker; 761 void *tdata; 762 flagword flags; 763 const struct bfd_arch_info *arch_info; 764 struct bfd_section *sections; 765 struct bfd_section *section_last; 766 unsigned int section_count; 767 struct bfd_hash_table section_htab; 768@}; 769 770@end example 771@findex bfd_preserve_save 772@subsubsection @code{bfd_preserve_save} 773@strong{Synopsis} 774@example 775bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *); 776@end example 777@strong{Description}@* 778When testing an object for compatibility with a particular 779target back-end, the back-end object_p function needs to set 780up certain fields in the bfd on successfully recognizing the 781object. This typically happens in a piecemeal fashion, with 782failures possible at many points. On failure, the bfd is 783supposed to be restored to its initial state, which is 784virtually impossible. However, restoring a subset of the bfd 785state works in practice. This function stores the subset and 786reinitializes the bfd. 787 788@findex bfd_preserve_restore 789@subsubsection @code{bfd_preserve_restore} 790@strong{Synopsis} 791@example 792void bfd_preserve_restore (bfd *, struct bfd_preserve *); 793@end example 794@strong{Description}@* 795This function restores bfd state saved by bfd_preserve_save. 796If MARKER is non-NULL in struct bfd_preserve then that block 797and all subsequently bfd_alloc'd memory is freed. 798 799@findex bfd_preserve_finish 800@subsubsection @code{bfd_preserve_finish} 801@strong{Synopsis} 802@example 803void bfd_preserve_finish (bfd *, struct bfd_preserve *); 804@end example 805@strong{Description}@* 806This function should be called when the bfd state saved by 807bfd_preserve_save is no longer needed. ie. when the back-end 808object_p function returns with success. 809 810@findex bfd_emul_get_maxpagesize 811@subsubsection @code{bfd_emul_get_maxpagesize} 812@strong{Synopsis} 813@example 814bfd_vma bfd_emul_get_maxpagesize (const char *); 815@end example 816@strong{Description}@* 817Returns the maximum page size, in bytes, as determined by 818emulation. 819 820@strong{Returns}@* 821Returns the maximum page size in bytes for ELF, abort 822otherwise. 823 824@findex bfd_emul_set_maxpagesize 825@subsubsection @code{bfd_emul_set_maxpagesize} 826@strong{Synopsis} 827@example 828void bfd_emul_set_maxpagesize (const char *, bfd_vma); 829@end example 830@strong{Description}@* 831For ELF, set the maximum page size for the emulation. It is 832a no-op for other formats. 833 834@findex bfd_emul_get_commonpagesize 835@subsubsection @code{bfd_emul_get_commonpagesize} 836@strong{Synopsis} 837@example 838bfd_vma bfd_emul_get_commonpagesize (const char *); 839@end example 840@strong{Description}@* 841Returns the common page size, in bytes, as determined by 842emulation. 843 844@strong{Returns}@* 845Returns the common page size in bytes for ELF, abort otherwise. 846 847@findex bfd_emul_set_commonpagesize 848@subsubsection @code{bfd_emul_set_commonpagesize} 849@strong{Synopsis} 850@example 851void bfd_emul_set_commonpagesize (const char *, bfd_vma); 852@end example 853@strong{Description}@* 854For ELF, set the common page size for the emulation. It is 855a no-op for other formats. 856 857@findex bfd_demangle 858@subsubsection @code{bfd_demangle} 859@strong{Synopsis} 860@example 861char *bfd_demangle (bfd *, const char *, int); 862@end example 863@strong{Description}@* 864Wrapper around cplus_demangle. Strips leading underscores and 865other such chars that would otherwise confuse the demangler. 866If passed a g++ v3 ABI mangled name, returns a buffer allocated 867with malloc holding the demangled name. Returns NULL otherwise 868and on memory alloc failure. 869 870