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