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