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