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