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