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