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