1 @node typedef bfd, Error reporting, BFD front end, BFD front end 2 @section @code{typedef bfd} 3 A BFD has type @code{bfd}; objects of this type are the 4 cornerstone of any application using BFD. Using BFD 5 consists of making references though the BFD and to data in the BFD. 6 7 Here is the structure that defines the type @code{bfd}. It 8 contains the major data about the file and pointers 9 to the rest of the data. 10 11 12 @example 13 struct 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 /* Do not attempt to modify this file. Set when detecting errors 215 that BFD is not prepared to handle for objcopy/strip. */ 216 unsigned int read_only : 1; 217 218 /* LTO object type. */ 219 ENUM_BITFIELD (bfd_lto_object_type) lto_type : 3; 220 221 /* Set if this BFD is currently being processed by 222 bfd_check_format_matches. This is checked by the cache to 223 avoid closing the BFD in this case. This should only be 224 examined or modified while the BFD lock is held. */ 225 unsigned int in_format_matches : 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 object-only section on the section list. */ 252 struct bfd_section *object_only_section; 253 254 /* The number of sections. */ 255 unsigned int section_count; 256 257 /* The archive plugin file descriptor. */ 258 int archive_plugin_fd; 259 260 /* The number of opens on the archive plugin file descriptor. */ 261 unsigned int archive_plugin_fd_open_count; 262 263 /* A field used by _bfd_generic_link_add_archive_symbols. This will 264 be used only for archive elements. */ 265 int archive_pass; 266 267 /* The total size of memory from bfd_alloc. */ 268 bfd_size_type alloc_size; 269 270 /* Stuff only useful for object files: 271 The start address. */ 272 bfd_vma start_address; 273 274 /* Symbol table for output BFD (with symcount entries). 275 Also used by the linker to cache input BFD symbols. */ 276 struct bfd_symbol **outsymbols; 277 278 /* Used for input and output. */ 279 unsigned int symcount; 280 281 /* Used for slurped dynamic symbol tables. */ 282 unsigned int dynsymcount; 283 284 /* Pointer to structure which contains architecture information. */ 285 const struct bfd_arch_info *arch_info; 286 287 /* Cached length of file for bfd_get_size. 0 until bfd_get_size is 288 called, 1 if stat returns an error or the file size is too large to 289 return in ufile_ptr. Both 0 and 1 should be treated as "unknown". */ 290 ufile_ptr size; 291 292 /* Stuff only useful for archives. */ 293 void *arelt_data; 294 struct bfd *my_archive; /* The containing archive BFD. */ 295 struct bfd *archive_next; /* The next BFD in the archive. */ 296 struct bfd *archive_head; /* The first BFD in the archive. */ 297 struct bfd *nested_archives; /* List of nested archive in a flattened 298 thin archive. */ 299 300 union @{ 301 /* For input BFDs, a chain of BFDs involved in a link. */ 302 struct bfd *next; 303 /* For output BFD, the linker hash table. */ 304 struct bfd_link_hash_table *hash; 305 @} link; 306 307 /* Used by the back end to hold private data. */ 308 union 309 @{ 310 struct aout_data_struct *aout_data; 311 struct artdata *aout_ar_data; 312 struct coff_tdata *coff_obj_data; 313 struct pe_tdata *pe_obj_data; 314 struct xcoff_tdata *xcoff_obj_data; 315 struct ecoff_tdata *ecoff_obj_data; 316 struct srec_data_struct *srec_data; 317 struct verilog_data_struct *verilog_data; 318 struct ihex_data_struct *ihex_data; 319 struct tekhex_data_struct *tekhex_data; 320 struct elf_obj_tdata *elf_obj_data; 321 struct mmo_data_struct *mmo_data; 322 struct trad_core_struct *trad_core_data; 323 struct som_data_struct *som_data; 324 struct hpux_core_struct *hpux_core_data; 325 struct hppabsd_core_struct *hppabsd_core_data; 326 struct sgi_core_struct *sgi_core_data; 327 struct lynx_core_struct *lynx_core_data; 328 struct osf_core_struct *osf_core_data; 329 struct cisco_core_struct *cisco_core_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 /* For input BFDs, mmapped entries. */ 353 struct bfd_mmapped *mmapped; 354 @}; 355 356 @end example 357 @node Error reporting, Initialization, typedef bfd, BFD front end 358 @section Error reporting 359 Most BFD functions return nonzero on success (check their 360 individual documentation for precise semantics). On an error, 361 they call @code{bfd_set_error} to set an error condition that callers 362 can check by calling @code{bfd_get_error}. 363 If that returns @code{bfd_error_system_call}, then check 364 @code{errno}. 365 366 The easiest way to report a BFD error to the user is to 367 use @code{bfd_perror}. 368 369 The BFD error is thread-local. 370 371 @subsection Type @code{bfd_error_type} 372 The values returned by @code{bfd_get_error} are defined by the 373 enumerated type @code{bfd_error_type}. 374 375 376 @example 377 typedef enum bfd_error 378 @{ 379 bfd_error_no_error = 0, 380 bfd_error_system_call, 381 bfd_error_invalid_target, 382 bfd_error_wrong_format, 383 bfd_error_wrong_object_format, 384 bfd_error_invalid_operation, 385 bfd_error_no_memory, 386 bfd_error_no_symbols, 387 bfd_error_no_armap, 388 bfd_error_no_more_archived_files, 389 bfd_error_malformed_archive, 390 bfd_error_missing_dso, 391 bfd_error_file_not_recognized, 392 bfd_error_file_ambiguously_recognized, 393 bfd_error_no_contents, 394 bfd_error_nonrepresentable_section, 395 bfd_error_no_debug_section, 396 bfd_error_bad_value, 397 bfd_error_file_truncated, 398 bfd_error_file_too_big, 399 bfd_error_sorry, 400 bfd_error_on_input, 401 bfd_error_invalid_error_code 402 @} 403 bfd_error_type; 404 405 @end example 406 @findex bfd_get_error 407 @subsubsection @code{bfd_get_error} 408 @deftypefn {Function} bfd_error_type bfd_get_error (void); 409 Return the current BFD error condition. 410 411 @end deftypefn 412 @findex bfd_set_error 413 @subsubsection @code{bfd_set_error} 414 @deftypefn {Function} void bfd_set_error (bfd_error_type error_tag); 415 Set the BFD error condition to be @var{error_tag}. 416 417 @var{error_tag} must not be bfd_error_on_input. Use 418 bfd_set_input_error for input errors instead. 419 420 @end deftypefn 421 @findex bfd_set_input_error 422 @subsubsection @code{bfd_set_input_error} 423 @deftypefn {Function} void bfd_set_input_error (bfd *input, bfd_error_type error_tag); 424 Set the BFD error condition to be bfd_error_on_input. 425 @var{input} is the input bfd where the error occurred, and 426 @var{error_tag} the bfd_error_type error. 427 428 @end deftypefn 429 @findex bfd_errmsg 430 @subsubsection @code{bfd_errmsg} 431 @deftypefn {Function} const char *bfd_errmsg (bfd_error_type error_tag); 432 Return a string describing the error @var{error_tag}, or 433 the system error if @var{error_tag} is @code{bfd_error_system_call}. 434 435 @end deftypefn 436 @findex bfd_perror 437 @subsubsection @code{bfd_perror} 438 @deftypefn {Function} void bfd_perror (const char *message); 439 Print to the standard error stream a string describing the 440 last BFD error that occurred, or the last system error if 441 the last BFD error was a system call failure. If @var{message} 442 is non-NULL and non-empty, the error string printed is preceded 443 by @var{message}, a colon, and a space. It is followed by a newline. 444 445 @end deftypefn 446 @findex bfd_asprintf 447 @subsubsection @code{bfd_asprintf} 448 @deftypefn {Function} char *bfd_asprintf (const char *fmt, ...); 449 Primarily for error reporting, this function is like 450 libiberty's xasprintf except that it can return NULL on no 451 memory and the returned string should not be freed. Uses a 452 thread-local malloc'd buffer managed by libbfd, _bfd_error_buf. 453 Be aware that a call to this function frees the result of any 454 previous call. bfd_errmsg (bfd_error_on_input) also calls 455 this function. 456 457 @end deftypefn 458 @subsection BFD error handler 459 Some BFD functions want to print messages describing the 460 problem. They call a BFD error handler function. This 461 function may be overridden by the program. 462 463 The BFD error handler acts like vprintf. 464 465 466 @example 467 typedef void (*bfd_error_handler_type) (const char *, va_list); 468 469 @end example 470 471 @example 472 typedef int (*bfd_print_callback) (void *, const char *, ...); 473 @end example 474 @findex bfd_print_error 475 @subsubsection @code{bfd_print_error} 476 @deftypefn {Function} void bfd_print_error (bfd_print_callback print_func, void *stream, const char *fmt, va_list ap); 477 This formats FMT and AP according to BFD "printf" rules, 478 sending the output to STREAM by repeated calls to PRINT_FUNC. 479 PRINT_FUNC is a printf-like function; it does not need to 480 implement the BFD printf format extensions. This can be used 481 in a callback that is set via bfd_set_error_handler to turn 482 the error into ordinary output. 483 484 @end deftypefn 485 @findex _bfd_error_handler 486 @subsubsection @code{_bfd_error_handler} 487 @deftypefn {Function} void _bfd_error_handler (const char *fmt, ...) ATTRIBUTE_PRINTF_1; 488 This is the default routine to handle BFD error messages. 489 Like fprintf (stderr, ...), but also handles some extra format 490 specifiers. 491 492 %pA section name from section. For group components, prints 493 group name too. 494 %pB file name from bfd. For archive components, prints 495 archive too. 496 497 Beware: Only supports a maximum of 9 format arguments. 498 499 @end deftypefn 500 @findex bfd_set_error_handler 501 @subsubsection @code{bfd_set_error_handler} 502 @deftypefn {Function} bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type); 503 Set the BFD error handler function. Returns the previous 504 function. 505 506 @end deftypefn 507 @findex _bfd_set_error_handler_caching 508 @subsubsection @code{_bfd_set_error_handler_caching} 509 @deftypefn {Function} struct per_xvec_messages *_bfd_set_error_handler_caching (struct per_xvec_messages *); 510 Set the BFD error handler function to one that stores messages 511 to the per_xvec_messages object. Returns the previous object 512 to which messages are stored. Note that two sequential calls 513 to this with a non-NULL argument will cause output to be 514 dropped, rather than gathered. 515 516 @end deftypefn 517 @findex _bfd_restore_error_handler_caching 518 @subsubsection @code{_bfd_restore_error_handler_caching} 519 @deftypefn {Function} void _bfd_restore_error_handler_caching (struct per_xvec_messages *); 520 Reset the BFD error handler object to an earlier value. 521 522 @end deftypefn 523 @findex bfd_set_error_program_name 524 @subsubsection @code{bfd_set_error_program_name} 525 @deftypefn {Function} void bfd_set_error_program_name (const char *); 526 Set the program name to use when printing a BFD error. This 527 is printed before the error message followed by a colon and 528 space. The string must not be changed after it is passed to 529 this function. 530 531 @end deftypefn 532 @findex _bfd_get_error_program_name 533 @subsubsection @code{_bfd_get_error_program_name} 534 @deftypefn {Function} const char *_bfd_get_error_program_name (void); 535 Get the program name used when printing a BFD error. 536 537 @end deftypefn 538 @subsection BFD assert handler 539 If BFD finds an internal inconsistency, the bfd assert 540 handler is called with information on the BFD version, BFD 541 source file and line. If this happens, most programs linked 542 against BFD are expected to want to exit with an error, or mark 543 the current BFD operation as failed, so it is recommended to 544 override the default handler, which just calls 545 _bfd_error_handler and continues. 546 547 548 @example 549 typedef void (*bfd_assert_handler_type) (const char *bfd_formatmsg, 550 const char *bfd_version, 551 const char *bfd_file, 552 int bfd_line); 553 554 @end example 555 @findex bfd_set_assert_handler 556 @subsubsection @code{bfd_set_assert_handler} 557 @deftypefn {Function} bfd_assert_handler_type bfd_set_assert_handler (bfd_assert_handler_type); 558 Set the BFD assert handler function. Returns the previous 559 function. 560 561 @end deftypefn 562 @node Initialization, Threading, Error reporting, BFD front end 563 @findex bfd_init 564 @subsubsection @code{bfd_init} 565 @deftypefn {Function} unsigned int bfd_init (void); 566 This routine must be called before any other BFD function to 567 initialize magical internal data structures. 568 Returns a magic number, which may be used to check 569 that the bfd library is configured as expected by users. 570 @example 571 /* Value returned by bfd_init. */ 572 #define BFD_INIT_MAGIC (sizeof (struct bfd_section)) 573 574 @end example 575 576 @end deftypefn 577 @node Threading, Miscellaneous, Initialization, BFD front end 578 @section Threading 579 BFD has limited support for thread-safety. Most BFD globals 580 are protected by locks, while the error-related globals are 581 thread-local. A given BFD cannot safely be used from two 582 threads at the same time; it is up to the application to do 583 any needed locking. However, it is ok for different threads 584 to work on different BFD objects at the same time. 585 586 @subsection Thread functions. 587 588 589 590 @example 591 typedef bool (*bfd_lock_unlock_fn_type) (void *); 592 @end example 593 @findex _bfd_threading_enabled 594 @subsubsection @code{_bfd_threading_enabled} 595 @deftypefn {Function} bool _bfd_threading_enabled (void); 596 Return true if threading is enabled, false if not. 597 598 @end deftypefn 599 @findex bfd_thread_init 600 @subsubsection @code{bfd_thread_init} 601 @deftypefn {Function} bool bfd_thread_init (bfd_lock_unlock_fn_type lock, bfd_lock_unlock_fn_type unlock, void *data); 602 Initialize BFD threading. The functions passed in will be 603 used to lock and unlock global data structures. This may only 604 be called a single time in a given process. Returns true on 605 success and false on error. On error, the caller should 606 assume that BFD cannot be used by multiple threads. DATA is 607 passed verbatim to the lock and unlock functions. The lock 608 and unlock functions should return true on success, or set the 609 BFD error and return false on failure. Note also that the 610 lock must be a recursive lock: BFD may attempt to acquire the 611 lock when it is already held by the current thread. 612 613 @end deftypefn 614 @findex bfd_thread_cleanup 615 @subsubsection @code{bfd_thread_cleanup} 616 @deftypefn {Function} void bfd_thread_cleanup (void); 617 Clean up any thread-local state. This should be called by a 618 thread that uses any BFD functions, before the thread exits. 619 It is fine to call this multiple times, or to call it and then 620 later call BFD functions on the same thread again. 621 622 @end deftypefn 623 @findex bfd_lock 624 @subsubsection @code{bfd_lock} 625 @deftypefn {Function} bool bfd_lock (void); 626 Acquire the global BFD lock, if needed. Returns true on 627 success, false on error. 628 629 @end deftypefn 630 @findex bfd_unlock 631 @subsubsection @code{bfd_unlock} 632 @deftypefn {Function} bool bfd_unlock (void); 633 Release the global BFD lock, if needed. Returns true on 634 success, false on error. 635 636 @end deftypefn 637 @node Miscellaneous, Memory Usage, Threading, BFD front end 638 @section Miscellaneous 639 640 641 @subsection Miscellaneous functions 642 643 644 @findex bfd_get_reloc_upper_bound 645 @subsubsection @code{bfd_get_reloc_upper_bound} 646 @deftypefn {Function} long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect); 647 Return the number of bytes required to store the 648 relocation information associated with section @var{sect} 649 attached to bfd @var{abfd}. If an error occurs, return -1. 650 651 @end deftypefn 652 @findex bfd_canonicalize_reloc 653 @subsubsection @code{bfd_canonicalize_reloc} 654 @deftypefn {Function} long bfd_canonicalize_reloc (bfd *abfd, asection *sec, arelent **loc, asymbol **syms); 655 Call the back end associated with the open BFD 656 @var{abfd} and translate the external form of the relocation 657 information attached to @var{sec} into the internal canonical 658 form. Place the table into memory at @var{loc}, which has 659 been preallocated, usually by a call to 660 @code{bfd_get_reloc_upper_bound}. Returns the number of relocs, or 661 -1 on error. 662 663 The @var{syms} table is also needed for horrible internal magic 664 reasons. 665 666 @end deftypefn 667 @findex bfd_finalize_section_relocs 668 @subsubsection @code{bfd_finalize_section_relocs} 669 @deftypefn {Function} bool bfd_finalize_section_relocs (bfd *abfd, asection *sec, arelent **rel, unsigned int count); 670 Set the relocation pointer and count within section @var{sec} 671 to the values @var{rel} and @var{count}, and take any other 672 actions required at the conclusion of section relocation 673 processing. 674 @example 675 #define bfd_finalize_section_relocs(abfd, asect, location, count) \ 676 BFD_SEND (abfd, _bfd_finalize_section_relocs, \ 677 (abfd, asect, location, count)) 678 @end example 679 680 @end deftypefn 681 @findex bfd_set_file_flags 682 @subsubsection @code{bfd_set_file_flags} 683 @deftypefn {Function} bool bfd_set_file_flags (bfd *abfd, flagword flags); 684 Set the flag word in the BFD @var{abfd} to the value @var{flags}. 685 686 Possible errors are: 687 @itemize @bullet 688 689 @item 690 @code{bfd_error_wrong_format} - The target bfd was not of object format. 691 @item 692 @code{bfd_error_invalid_operation} - The target bfd was open for reading. 693 @item 694 @code{bfd_error_invalid_operation} - 695 The flag word contained a bit which was not applicable to the 696 type of file. E.g., an attempt was made to set the @code{D_PAGED} bit 697 on a BFD format which does not support demand paging. 698 @end itemize 699 700 @end deftypefn 701 @findex bfd_get_arch_size 702 @subsubsection @code{bfd_get_arch_size} 703 @deftypefn {Function} int bfd_get_arch_size (bfd *abfd); 704 Returns the normalized architecture address size, in bits, as 705 determined by the object file's format. By normalized, we mean 706 either 32 or 64. For ELF, this information is included in the 707 header. Use bfd_arch_bits_per_address for number of bits in 708 the architecture address. 709 710 Returns the arch size in bits if known, @code{-1} otherwise. 711 712 @end deftypefn 713 @findex bfd_get_sign_extend_vma 714 @subsubsection @code{bfd_get_sign_extend_vma} 715 @deftypefn {Function} int bfd_get_sign_extend_vma (bfd *abfd); 716 Indicates if the target architecture "naturally" sign extends 717 an address. Some architectures implicitly sign extend address 718 values when they are converted to types larger than the size 719 of an address. For instance, bfd_get_start_address() will 720 return an address sign extended to fill a bfd_vma when this is 721 the case. 722 723 Returns @code{1} if the target architecture is known to sign 724 extend addresses, @code{0} if the target architecture is known to 725 not sign extend addresses, and @code{-1} otherwise. 726 727 @end deftypefn 728 @findex bfd_set_start_address 729 @subsubsection @code{bfd_set_start_address} 730 @deftypefn {Function} bool bfd_set_start_address (bfd *abfd, bfd_vma vma); 731 Make @var{vma} the entry point of output BFD @var{abfd}. 732 733 Returns @code{TRUE} on success, @code{FALSE} otherwise. 734 735 @end deftypefn 736 @findex bfd_get_gp_size 737 @subsubsection @code{bfd_get_gp_size} 738 @deftypefn {Function} unsigned int bfd_get_gp_size (bfd *abfd); 739 Return the maximum size of objects to be optimized using the GP 740 register under MIPS ECOFF. This is typically set by the @code{-G} 741 argument to the compiler, assembler or linker. 742 743 @end deftypefn 744 @findex bfd_set_gp_size 745 @subsubsection @code{bfd_set_gp_size} 746 @deftypefn {Function} void bfd_set_gp_size (bfd *abfd, unsigned int i); 747 Set the maximum size of objects to be optimized using the GP 748 register under ECOFF or MIPS ELF. This is typically set by 749 the @code{-G} argument to the compiler, assembler or linker. 750 751 @end deftypefn 752 @findex bfd_set_gp_value 753 @subsubsection @code{bfd_set_gp_value} 754 @deftypefn {Function} void bfd_set_gp_value (bfd *abfd, bfd_vma v); 755 Allow external access to the fucntion to set the GP value. 756 This is specifically added for gdb-compile support. 757 758 @end deftypefn 759 @findex bfd_scan_vma 760 @subsubsection @code{bfd_scan_vma} 761 @deftypefn {Function} bfd_vma bfd_scan_vma (const char *string, const char **end, int base); 762 Convert, like @code{strtoul} or @code{stdtoull}depending on the size 763 of a @code{bfd_vma}, a numerical expression @var{string} into a 764 @code{bfd_vma} integer, and return that integer. 765 766 @end deftypefn 767 @findex bfd_copy_private_header_data 768 @subsubsection @code{bfd_copy_private_header_data} 769 @deftypefn {Function} bool bfd_copy_private_header_data (bfd *ibfd, bfd *obfd); 770 Copy private BFD header information from the BFD @var{ibfd} to the 771 the BFD @var{obfd}. This copies information that may require 772 sections to exist, but does not require symbol tables. Return 773 @code{true} on success, @code{false} on error. 774 Possible error returns are: 775 776 @itemize @bullet 777 778 @item 779 @code{bfd_error_no_memory} - 780 Not enough memory exists to create private data for @var{obfd}. 781 @end itemize 782 @example 783 #define bfd_copy_private_header_data(ibfd, obfd) \ 784 BFD_SEND (obfd, _bfd_copy_private_header_data, \ 785 (ibfd, obfd)) 786 @end example 787 788 @end deftypefn 789 @findex bfd_copy_private_bfd_data 790 @subsubsection @code{bfd_copy_private_bfd_data} 791 @deftypefn {Function} bool bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd); 792 Copy private BFD information from the BFD @var{ibfd} to the 793 the BFD @var{obfd}. Return @code{TRUE} on success, @code{FALSE} on error. 794 Possible error returns are: 795 796 @itemize @bullet 797 798 @item 799 @code{bfd_error_no_memory} - 800 Not enough memory exists to create private data for @var{obfd}. 801 @end itemize 802 @example 803 #define bfd_copy_private_bfd_data(ibfd, obfd) \ 804 BFD_SEND (obfd, _bfd_copy_private_bfd_data, \ 805 (ibfd, obfd)) 806 @end example 807 808 @end deftypefn 809 @findex bfd_set_private_flags 810 @subsubsection @code{bfd_set_private_flags} 811 @deftypefn {Function} bool bfd_set_private_flags (bfd *abfd, flagword flags); 812 Set private BFD flag information in the BFD @var{abfd}. 813 Return @code{TRUE} on success, @code{FALSE} on error. Possible error 814 returns are: 815 816 @itemize @bullet 817 818 @item 819 @code{bfd_error_no_memory} - 820 Not enough memory exists to create private data for @var{obfd}. 821 @end itemize 822 @example 823 #define bfd_set_private_flags(abfd, flags) \ 824 BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags)) 825 @end example 826 827 @end deftypefn 828 @findex Other functions 829 @subsubsection @code{Other functions} 830 The following functions exist but have not yet been documented. 831 @example 832 #define bfd_sizeof_headers(abfd, info) \ 833 BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info)) 834 835 #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \ 836 BFD_SEND (abfd, _bfd_find_nearest_line, \ 837 (abfd, syms, sec, off, file, func, line, NULL)) 838 839 #define bfd_find_nearest_line_with_alt(abfd, alt_filename, sec, syms, off, \ 840 file, func, line, disc) \ 841 BFD_SEND (abfd, _bfd_find_nearest_line_with_alt, \ 842 (abfd, alt_filename, syms, sec, off, file, func, line, disc)) 843 844 #define bfd_find_nearest_line_discriminator(abfd, sec, syms, off, file, func, \ 845 line, disc) \ 846 BFD_SEND (abfd, _bfd_find_nearest_line, \ 847 (abfd, syms, sec, off, file, func, line, disc)) 848 849 #define bfd_find_line(abfd, syms, sym, file, line) \ 850 BFD_SEND (abfd, _bfd_find_line, \ 851 (abfd, syms, sym, file, line)) 852 853 #define bfd_find_inliner_info(abfd, file, func, line) \ 854 BFD_SEND (abfd, _bfd_find_inliner_info, \ 855 (abfd, file, func, line)) 856 857 #define bfd_debug_info_start(abfd) \ 858 BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) 859 860 #define bfd_debug_info_end(abfd) \ 861 BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) 862 863 #define bfd_debug_info_accumulate(abfd, section) \ 864 BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) 865 866 #define bfd_stat_arch_elt(abfd, stat) \ 867 BFD_SEND (abfd->my_archive ? abfd->my_archive : abfd, \ 868 _bfd_stat_arch_elt, (abfd, stat)) 869 870 #define bfd_update_armap_timestamp(abfd) \ 871 BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd)) 872 873 #define bfd_set_arch_mach(abfd, arch, mach)\ 874 BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) 875 876 #define bfd_relax_section(abfd, section, link_info, again) \ 877 BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again)) 878 879 #define bfd_gc_sections(abfd, link_info) \ 880 BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info)) 881 882 #define bfd_lookup_section_flags(link_info, flag_info, section) \ 883 BFD_SEND (abfd, _bfd_lookup_section_flags, (link_info, flag_info, section)) 884 885 #define bfd_is_group_section(abfd, sec) \ 886 BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec)) 887 888 #define bfd_group_name(abfd, sec) \ 889 BFD_SEND (abfd, _bfd_group_name, (abfd, sec)) 890 891 #define bfd_discard_group(abfd, sec) \ 892 BFD_SEND (abfd, _bfd_discard_group, (abfd, sec)) 893 894 #define bfd_link_hash_table_create(abfd) \ 895 BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd)) 896 897 #define bfd_link_add_symbols(abfd, info) \ 898 BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info)) 899 900 #define bfd_link_just_syms(abfd, sec, info) \ 901 BFD_SEND (abfd, _bfd_link_just_syms, (sec, info)) 902 903 #define bfd_final_link(abfd, info) \ 904 BFD_SEND (abfd, _bfd_final_link, (abfd, info)) 905 906 #define bfd_free_cached_info(abfd) \ 907 BFD_SEND (abfd, _bfd_free_cached_info, (abfd)) 908 909 #define bfd_get_dynamic_symtab_upper_bound(abfd) \ 910 BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd)) 911 912 #define bfd_print_private_bfd_data(abfd, file)\ 913 BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file)) 914 915 #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \ 916 BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols)) 917 918 #define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \ 919 BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \ 920 dyncount, dynsyms, ret)) 921 922 #define bfd_get_dynamic_reloc_upper_bound(abfd) \ 923 BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd)) 924 925 #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \ 926 BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms)) 927 928 @end example 929 930 @findex bfd_get_relocated_section_contents 931 @subsubsection @code{bfd_get_relocated_section_contents} 932 @deftypefn {Function} bfd_byte *bfd_get_relocated_section_contents (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *, bool, asymbol **); 933 Read and relocate the indirect link_order section, into DATA 934 (if non-NULL) or to a malloc'd buffer. Return the buffer, or 935 NULL on errors. 936 937 @end deftypefn 938 @findex bfd_record_phdr 939 @subsubsection @code{bfd_record_phdr} 940 @deftypefn {Function} bool bfd_record_phdr (bfd *, unsigned long, bool, flagword, bool, bfd_vma, bool, bool, unsigned int, struct bfd_section **); 941 Record information about an ELF program header. 942 943 @end deftypefn 944 @findex bfd_sprintf_vma 945 @subsubsection @code{bfd_sprintf_vma} 946 @deftypefn {Function} void bfd_sprintf_vma (bfd *, char *, bfd_vma); void bfd_fprintf_vma (bfd *, void *, bfd_vma); 947 bfd_sprintf_vma and bfd_fprintf_vma display an address in the 948 target's address size. 949 950 @end deftypefn 951 @findex bfd_alt_mach_code 952 @subsubsection @code{bfd_alt_mach_code} 953 @deftypefn {Function} bool bfd_alt_mach_code (bfd *abfd, int alternative); 954 When more than one machine code number is available for the 955 same machine type, this function can be used to switch between 956 the preferred one (alternative == 0) and any others. Currently, 957 only ELF supports this feature, with up to two alternate 958 machine codes. 959 960 @end deftypefn 961 @findex bfd_emul_get_maxpagesize 962 @subsubsection @code{bfd_emul_get_maxpagesize} 963 @deftypefn {Function} bfd_vma bfd_emul_get_maxpagesize (const char *); 964 Returns the maximum page size, in bytes, as determined by 965 emulation. 966 967 @end deftypefn 968 @findex bfd_emul_get_commonpagesize 969 @subsubsection @code{bfd_emul_get_commonpagesize} 970 @deftypefn {Function} bfd_vma bfd_emul_get_commonpagesize (const char *); 971 Returns the common page size, in bytes, as determined by 972 emulation. 973 974 @end deftypefn 975 @findex bfd_demangle 976 @subsubsection @code{bfd_demangle} 977 @deftypefn {Function} char *bfd_demangle (bfd *, const char *, int); 978 Wrapper around cplus_demangle. Strips leading underscores and 979 other such chars that would otherwise confuse the demangler. 980 If passed a g++ v3 ABI mangled name, returns a buffer allocated 981 with malloc holding the demangled name. Returns NULL otherwise 982 and on memory alloc failure. 983 984 @end deftypefn 985 @findex bfd_group_signature 986 @subsubsection @code{bfd_group_signature} 987 @deftypefn {Function} asymbol *bfd_group_signature (asection *group, asymbol **isympp); 988 Return a pointer to the symbol used as a signature for GROUP. 989 990 @end deftypefn 991
Indexes created Tue Mar 03 05:31:39 UTC 2026