1 2@example 3/* Set to N to open the next N BFDs using an alternate id space. */ 4extern unsigned int bfd_use_reserved_id; 5@end example 6@section Opening and closing BFDs 7 8 9@subsection Functions for opening and closing 10 11 12@findex bfd_fopen 13@subsubsection @code{bfd_fopen} 14@strong{Synopsis} 15@example 16bfd *bfd_fopen (const char *filename, const char *target, 17 const char *mode, int fd); 18@end example 19@strong{Description}@* 20Open the file @var{filename} with the target @var{target}. 21Return a pointer to the created BFD. If @var{fd} is not -1, 22then @code{fdopen} is used to open the file; otherwise, @code{fopen} 23is used. @var{mode} is passed directly to @code{fopen} or 24@code{fdopen}. 25 26Calls @code{bfd_find_target}, so @var{target} is interpreted as by 27that function. 28 29The new BFD is marked as cacheable iff @var{fd} is -1. 30 31If @code{NULL} is returned then an error has occured. Possible errors 32are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or 33@code{system_call} error. 34 35On error, @var{fd} is always closed. 36 37A copy of the @var{filename} argument is stored in the newly created 38BFD. It can be accessed via the bfd_get_filename() macro. 39 40@findex bfd_openr 41@subsubsection @code{bfd_openr} 42@strong{Synopsis} 43@example 44bfd *bfd_openr (const char *filename, const char *target); 45@end example 46@strong{Description}@* 47Open the file @var{filename} (using @code{fopen}) with the target 48@var{target}. Return a pointer to the created BFD. 49 50Calls @code{bfd_find_target}, so @var{target} is interpreted as by 51that function. 52 53If @code{NULL} is returned then an error has occured. Possible errors 54are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or 55@code{system_call} error. 56 57A copy of the @var{filename} argument is stored in the newly created 58BFD. It can be accessed via the bfd_get_filename() macro. 59 60@findex bfd_fdopenr 61@subsubsection @code{bfd_fdopenr} 62@strong{Synopsis} 63@example 64bfd *bfd_fdopenr (const char *filename, const char *target, int fd); 65@end example 66@strong{Description}@* 67@code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to 68@code{fopen}. It opens a BFD on a file already described by the 69@var{fd} supplied. 70 71When the file is later @code{bfd_close}d, the file descriptor will 72be closed. If the caller desires that this file descriptor be 73cached by BFD (opened as needed, closed as needed to free 74descriptors for other opens), with the supplied @var{fd} used as 75an initial file descriptor (but subject to closure at any time), 76call bfd_set_cacheable(bfd, 1) on the returned BFD. The default 77is to assume no caching; the file descriptor will remain open 78until @code{bfd_close}, and will not be affected by BFD operations 79on other files. 80 81Possible errors are @code{bfd_error_no_memory}, 82@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. 83 84On error, @var{fd} is closed. 85 86A copy of the @var{filename} argument is stored in the newly created 87BFD. It can be accessed via the bfd_get_filename() macro. 88 89@findex bfd_openstreamr 90@subsubsection @code{bfd_openstreamr} 91@strong{Synopsis} 92@example 93bfd *bfd_openstreamr (const char * filename, const char * target, void * stream); 94@end example 95@strong{Description}@* 96Open a BFD for read access on an existing stdio stream. When 97the BFD is passed to @code{bfd_close}, the stream will be closed. 98 99A copy of the @var{filename} argument is stored in the newly created 100BFD. It can be accessed via the bfd_get_filename() macro. 101 102@findex bfd_openr_iovec 103@subsubsection @code{bfd_openr_iovec} 104@strong{Synopsis} 105@example 106bfd *bfd_openr_iovec (const char *filename, const char *target, 107 void *(*open_func) (struct bfd *nbfd, 108 void *open_closure), 109 void *open_closure, 110 file_ptr (*pread_func) (struct bfd *nbfd, 111 void *stream, 112 void *buf, 113 file_ptr nbytes, 114 file_ptr offset), 115 int (*close_func) (struct bfd *nbfd, 116 void *stream), 117 int (*stat_func) (struct bfd *abfd, 118 void *stream, 119 struct stat *sb)); 120@end example 121@strong{Description}@* 122Create and return a BFD backed by a read-only @var{stream}. 123The @var{stream} is created using @var{open_func}, accessed using 124@var{pread_func} and destroyed using @var{close_func}. 125 126Calls @code{bfd_find_target}, so @var{target} is interpreted as by 127that function. 128 129Calls @var{open_func} (which can call @code{bfd_zalloc} and 130@code{bfd_get_filename}) to obtain the read-only stream backing 131the BFD. @var{open_func} either succeeds returning the 132non-@code{NULL} @var{stream}, or fails returning @code{NULL} 133(setting @code{bfd_error}). 134 135Calls @var{pread_func} to request @var{nbytes} of data from 136@var{stream} starting at @var{offset} (e.g., via a call to 137@code{bfd_read}). @var{pread_func} either succeeds returning the 138number of bytes read (which can be less than @var{nbytes} when 139end-of-file), or fails returning -1 (setting @code{bfd_error}). 140 141Calls @var{close_func} when the BFD is later closed using 142@code{bfd_close}. @var{close_func} either succeeds returning 0, or 143fails returning -1 (setting @code{bfd_error}). 144 145Calls @var{stat_func} to fill in a stat structure for bfd_stat, 146bfd_get_size, and bfd_get_mtime calls. @var{stat_func} returns 0 147on success, or returns -1 on failure (setting @code{bfd_error}). 148 149If @code{bfd_openr_iovec} returns @code{NULL} then an error has 150occurred. Possible errors are @code{bfd_error_no_memory}, 151@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. 152 153A copy of the @var{filename} argument is stored in the newly created 154BFD. It can be accessed via the bfd_get_filename() macro. 155 156@findex bfd_openw 157@subsubsection @code{bfd_openw} 158@strong{Synopsis} 159@example 160bfd *bfd_openw (const char *filename, const char *target); 161@end example 162@strong{Description}@* 163Create a BFD, associated with file @var{filename}, using the 164file format @var{target}, and return a pointer to it. 165 166Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory}, 167@code{bfd_error_invalid_target}. 168 169A copy of the @var{filename} argument is stored in the newly created 170BFD. It can be accessed via the bfd_get_filename() macro. 171 172@findex bfd_close 173@subsubsection @code{bfd_close} 174@strong{Synopsis} 175@example 176bfd_boolean bfd_close (bfd *abfd); 177@end example 178@strong{Description}@* 179Close a BFD. If the BFD was open for writing, then pending 180operations are completed and the file written out and closed. 181If the created file is executable, then @code{chmod} is called 182to mark it as such. 183 184All memory attached to the BFD is released. 185 186The file descriptor associated with the BFD is closed (even 187if it was passed in to BFD by @code{bfd_fdopenr}). 188 189@strong{Returns}@* 190@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 191 192@findex bfd_close_all_done 193@subsubsection @code{bfd_close_all_done} 194@strong{Synopsis} 195@example 196bfd_boolean bfd_close_all_done (bfd *); 197@end example 198@strong{Description}@* 199Close a BFD. Differs from @code{bfd_close} since it does not 200complete any pending operations. This routine would be used 201if the application had just used BFD for swapping and didn't 202want to use any of the writing code. 203 204If the created file is executable, then @code{chmod} is called 205to mark it as such. 206 207All memory attached to the BFD is released. 208 209@strong{Returns}@* 210@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 211 212@findex bfd_create 213@subsubsection @code{bfd_create} 214@strong{Synopsis} 215@example 216bfd *bfd_create (const char *filename, bfd *templ); 217@end example 218@strong{Description}@* 219Create a new BFD in the manner of @code{bfd_openw}, but without 220opening a file. The new BFD takes the target from the target 221used by @var{templ}. The format is always set to @code{bfd_object}. 222 223A copy of the @var{filename} argument is stored in the newly created 224BFD. It can be accessed via the bfd_get_filename() macro. 225 226@findex bfd_make_writable 227@subsubsection @code{bfd_make_writable} 228@strong{Synopsis} 229@example 230bfd_boolean bfd_make_writable (bfd *abfd); 231@end example 232@strong{Description}@* 233Takes a BFD as created by @code{bfd_create} and converts it 234into one like as returned by @code{bfd_openw}. It does this 235by converting the BFD to BFD_IN_MEMORY. It's assumed that 236you will call @code{bfd_make_readable} on this bfd later. 237 238@strong{Returns}@* 239@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 240 241@findex bfd_make_readable 242@subsubsection @code{bfd_make_readable} 243@strong{Synopsis} 244@example 245bfd_boolean bfd_make_readable (bfd *abfd); 246@end example 247@strong{Description}@* 248Takes a BFD as created by @code{bfd_create} and 249@code{bfd_make_writable} and converts it into one like as 250returned by @code{bfd_openr}. It does this by writing the 251contents out to the memory buffer, then reversing the 252direction. 253 254@strong{Returns}@* 255@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 256 257@findex bfd_alloc 258@subsubsection @code{bfd_alloc} 259@strong{Synopsis} 260@example 261void *bfd_alloc (bfd *abfd, bfd_size_type wanted); 262@end example 263@strong{Description}@* 264Allocate a block of @var{wanted} bytes of memory attached to 265@code{abfd} and return a pointer to it. 266 267@findex bfd_alloc2 268@subsubsection @code{bfd_alloc2} 269@strong{Synopsis} 270@example 271void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size); 272@end example 273@strong{Description}@* 274Allocate a block of @var{nmemb} elements of @var{size} bytes each 275of memory attached to @code{abfd} and return a pointer to it. 276 277@findex bfd_zalloc 278@subsubsection @code{bfd_zalloc} 279@strong{Synopsis} 280@example 281void *bfd_zalloc (bfd *abfd, bfd_size_type wanted); 282@end example 283@strong{Description}@* 284Allocate a block of @var{wanted} bytes of zeroed memory 285attached to @code{abfd} and return a pointer to it. 286 287@findex bfd_zalloc2 288@subsubsection @code{bfd_zalloc2} 289@strong{Synopsis} 290@example 291void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size); 292@end example 293@strong{Description}@* 294Allocate a block of @var{nmemb} elements of @var{size} bytes each 295of zeroed memory attached to @code{abfd} and return a pointer to it. 296 297@findex bfd_calc_gnu_debuglink_crc32 298@subsubsection @code{bfd_calc_gnu_debuglink_crc32} 299@strong{Synopsis} 300@example 301unsigned long bfd_calc_gnu_debuglink_crc32 302 (unsigned long crc, const unsigned char *buf, bfd_size_type len); 303@end example 304@strong{Description}@* 305Computes a CRC value as used in the .gnu_debuglink section. 306Advances the previously computed @var{crc} value by computing 307and adding in the crc32 for @var{len} bytes of @var{buf}. 308 309@strong{Returns}@* 310Return the updated CRC32 value. 311 312@findex bfd_get_debug_link_info 313@subsubsection @code{bfd_get_debug_link_info} 314@strong{Synopsis} 315@example 316char *bfd_get_debug_link_info (bfd *abfd, unsigned long *crc32_out); 317@end example 318@strong{Description}@* 319Fetch the filename and CRC32 value for any separate debuginfo 320associated with @var{abfd}. Return NULL if no such info found, 321otherwise return filename and update @var{crc32_out}. The 322returned filename is allocated with @code{malloc}; freeing it 323is the responsibility of the caller. 324 325@findex bfd_get_alt_debug_link_info 326@subsubsection @code{bfd_get_alt_debug_link_info} 327@strong{Synopsis} 328@example 329char *bfd_get_alt_debug_link_info (bfd * abfd, 330 bfd_size_type *buildid_len, 331 bfd_byte **buildid_out); 332@end example 333@strong{Description}@* 334Fetch the filename and BuildID value for any alternate debuginfo 335associated with @var{abfd}. Return NULL if no such info found, 336otherwise return filename and update @var{buildid_len} and 337@var{buildid_out}. The returned filename and build_id are 338allocated with @code{malloc}; freeing them is the 339responsibility of the caller. 340 341@findex separate_debug_file_exists 342@subsubsection @code{separate_debug_file_exists} 343@strong{Synopsis} 344@example 345bfd_boolean separate_debug_file_exists 346 (char *name, unsigned long crc32); 347@end example 348@strong{Description}@* 349Checks to see if @var{name} is a file and if its contents 350match @var{crc32}. 351 352@findex separate_alt_debug_file_exists 353@subsubsection @code{separate_alt_debug_file_exists} 354@strong{Synopsis} 355@example 356bfd_boolean separate_alt_debug_file_exists 357 (char *name, unsigned long buildid); 358@end example 359@strong{Description}@* 360Checks to see if @var{name} is a file and if its BuildID 361matches @var{buildid}. 362 363@findex find_separate_debug_file 364@subsubsection @code{find_separate_debug_file} 365@strong{Synopsis} 366@example 367char *find_separate_debug_file 368 (bfd *abfd, const char *dir, bfd_boolean include_dirs, 369 get_func_type get, check_func_type check); 370@end example 371@strong{Description}@* 372Searches for a debug information file corresponding to @var{abfd}. 373The name of the separate debug info file is returned by the @var{get} 374function. This function scans various fixed locations in the 375filesystem, including the file tree rooted at @var{dir}. If the 376@var{include_dirs} parameter is true then the directory components of 377@var{abfd}'s filename will be included in the searched locations. 378 379Returns the filename of the first file to be found which receives a 380TRUE result from the @var{check} function. Returns NULL if no valid 381file could be found. 382 383@findex bfd_follow_gnu_debuglink 384@subsubsection @code{bfd_follow_gnu_debuglink} 385@strong{Synopsis} 386@example 387char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir); 388@end example 389@strong{Description}@* 390Takes a BFD and searches it for a .gnu_debuglink section. If this 391section is found, it examines the section for the name and checksum 392of a '.debug' file containing auxiliary debugging information. It 393then searches the filesystem for this .debug file in some standard 394locations, including the directory tree rooted at @var{dir}, and if 395found returns the full filename. 396 397If @var{dir} is NULL, the search will take place starting at 398the current directory. 399 400@strong{Returns}@* 401@code{NULL} on any errors or failure to locate the .debug file, 402otherwise a pointer to a heap-allocated string containing the 403filename. The caller is responsible for freeing this string. 404 405@findex bfd_follow_gnu_debugaltlink 406@subsubsection @code{bfd_follow_gnu_debugaltlink} 407@strong{Synopsis} 408@example 409char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir); 410@end example 411@strong{Description}@* 412Takes a BFD and searches it for a .gnu_debugaltlink section. If this 413section is found, it examines the section for the name of a file 414containing auxiliary debugging information. It then searches the 415filesystem for this file in a set of standard locations, including 416the directory tree rooted at @var{dir}, and if found returns the 417full filename. 418 419If @var{dir} is NULL, the search will take place starting at 420the current directory. 421 422@strong{Returns}@* 423@code{NULL} on any errors or failure to locate the debug file, 424otherwise a pointer to a heap-allocated string containing the 425filename. The caller is responsible for freeing this string. 426 427@findex bfd_create_gnu_debuglink_section 428@subsubsection @code{bfd_create_gnu_debuglink_section} 429@strong{Synopsis} 430@example 431struct bfd_section *bfd_create_gnu_debuglink_section 432 (bfd *abfd, const char *filename); 433@end example 434@strong{Description}@* 435Takes a @var{BFD} and adds a .gnu_debuglink section to it. The section is sized 436to be big enough to contain a link to the specified @var{filename}. 437 438@strong{Returns}@* 439A pointer to the new section is returned if all is ok. Otherwise @code{NULL} is 440returned and bfd_error is set. 441 442@findex bfd_fill_in_gnu_debuglink_section 443@subsubsection @code{bfd_fill_in_gnu_debuglink_section} 444@strong{Synopsis} 445@example 446bfd_boolean bfd_fill_in_gnu_debuglink_section 447 (bfd *abfd, struct bfd_section *sect, const char *filename); 448@end example 449@strong{Description}@* 450Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT} 451and fills in the contents of the section to contain a link to the 452specified @var{filename}. The filename should be relative to the 453current directory. 454 455@strong{Returns}@* 456@code{TRUE} is returned if all is ok. Otherwise @code{FALSE} is returned 457and bfd_error is set. 458 459@findex get_build_id 460@subsubsection @code{get_build_id} 461@strong{Synopsis} 462@example 463struct bfd_build_id * get_build_id 464 (bfd *abfd); 465@end example 466@strong{Description}@* 467Finds the build-id associated with @var{abfd}. If the build-id is 468extracted from the note section then a build-id structure is built 469for it, using memory allocated to @var{abfd}, and this is then 470attached to the @var{abfd}. 471 472Returns a pointer to the build-id structure if a build-id could be 473found. If no build-id is found NULL is returned and error code is 474set. 475 476@findex get_build_id_name 477@subsubsection @code{get_build_id_name} 478@strong{Synopsis} 479@example 480char * get_build_id_name 481 (bfd *abfd, unsigned long *build_id_out) 482@end example 483@strong{Description}@* 484Searches @var{abfd} for a build-id, and then constructs a pathname 485from it. The path is computed as .build-id/NN/NN+NN.debug where 486NNNN+NN is the build-id value as a hexadecimal string. 487 488Returns the constructed filename or NULL upon error. 489It is the caller's responsibility to free the memory used to hold the 490filename. 491If a filename is returned then the @var{build_id_out} parameter is 492set to a pointer to the build_id structure. 493 494@findex check_build_id_file 495@subsubsection @code{check_build_id_file} 496@strong{Synopsis} 497@example 498bfd_boolean check_build_id_file 499 (char *name, unsigned long buildid); 500@end example 501@strong{Description}@* 502Checks to see if @var{name} is a readable file and if its build-id 503matches @var{buildid}. 504 505Returns TRUE if the file exists, is readable, and contains a build-id 506which matches @var{build-id}. 507 508@findex bfd_follow_build_id_debuglink 509@subsubsection @code{bfd_follow_build_id_debuglink} 510@strong{Synopsis} 511@example 512char *bfd_follow_build_id_debuglink (bfd *abfd, const char *dir); 513@end example 514@strong{Description}@* 515Takes @var{abfd} and searches it for a .note.gnu.build-id section. 516If this section is found, it extracts the value of the NT_GNU_BUILD_ID 517note, which should be a hexadecimal value @var{NNNN+NN} (for 51832+ hex digits). It then searches the filesystem for a file named 519@var{.build-id/NN/NN+NN.debug} in a set of standard locations, 520including the directory tree rooted at @var{dir}. The filename 521of the first matching file to be found is returned. A matching 522file should contain a .note.gnu.build-id section with the same 523@var{NNNN+NN} note as @var{abfd}, although this check is currently 524not implemented. 525 526If @var{dir} is NULL, the search will take place starting at 527the current directory. 528 529@strong{Returns}@* 530@code{NULL} on any errors or failure to locate the debug file, 531otherwise a pointer to a heap-allocated string containing the 532filename. The caller is responsible for freeing this string. 533 534