opncls.texi revision 1.1.1.7
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_fdopenw 90@subsubsection @code{bfd_fdopenw} 91@strong{Synopsis} 92@example 93bfd *bfd_fdopenw (const char *filename, const char *target, int fd); 94@end example 95@strong{Description}@* 96@code{bfd_fdopenw} is exactly like @code{bfd_fdopenr} with the exception that 97the resulting BFD is suitable for output. 98 99@findex bfd_openstreamr 100@subsubsection @code{bfd_openstreamr} 101@strong{Synopsis} 102@example 103bfd *bfd_openstreamr (const char * filename, const char * target, 104 void * stream); 105@end example 106@strong{Description}@* 107Open a BFD for read access on an existing stdio stream. When 108the BFD is passed to @code{bfd_close}, the stream will be closed. 109 110A copy of the @var{filename} argument is stored in the newly created 111BFD. It can be accessed via the bfd_get_filename() macro. 112 113@findex bfd_openr_iovec 114@subsubsection @code{bfd_openr_iovec} 115@strong{Synopsis} 116@example 117bfd *bfd_openr_iovec (const char *filename, const char *target, 118 void *(*open_func) (struct bfd *nbfd, 119 void *open_closure), 120 void *open_closure, 121 file_ptr (*pread_func) (struct bfd *nbfd, 122 void *stream, 123 void *buf, 124 file_ptr nbytes, 125 file_ptr offset), 126 int (*close_func) (struct bfd *nbfd, 127 void *stream), 128 int (*stat_func) (struct bfd *abfd, 129 void *stream, 130 struct stat *sb)); 131@end example 132@strong{Description}@* 133Create and return a BFD backed by a read-only @var{stream}. 134The @var{stream} is created using @var{open_func}, accessed using 135@var{pread_func} and destroyed using @var{close_func}. 136 137Calls @code{bfd_find_target}, so @var{target} is interpreted as by 138that function. 139 140Calls @var{open_func} (which can call @code{bfd_zalloc} and 141@code{bfd_get_filename}) to obtain the read-only stream backing 142the BFD. @var{open_func} either succeeds returning the 143non-@code{NULL} @var{stream}, or fails returning @code{NULL} 144(setting @code{bfd_error}). 145 146Calls @var{pread_func} to request @var{nbytes} of data from 147@var{stream} starting at @var{offset} (e.g., via a call to 148@code{bfd_read}). @var{pread_func} either succeeds returning the 149number of bytes read (which can be less than @var{nbytes} when 150end-of-file), or fails returning -1 (setting @code{bfd_error}). 151 152Calls @var{close_func} when the BFD is later closed using 153@code{bfd_close}. @var{close_func} either succeeds returning 0, or 154fails returning -1 (setting @code{bfd_error}). 155 156Calls @var{stat_func} to fill in a stat structure for bfd_stat, 157bfd_get_size, and bfd_get_mtime calls. @var{stat_func} returns 0 158on success, or returns -1 on failure (setting @code{bfd_error}). 159 160If @code{bfd_openr_iovec} returns @code{NULL} then an error has 161occurred. Possible errors are @code{bfd_error_no_memory}, 162@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. 163 164A copy of the @var{filename} argument is stored in the newly created 165BFD. It can be accessed via the bfd_get_filename() macro. 166 167@findex bfd_openw 168@subsubsection @code{bfd_openw} 169@strong{Synopsis} 170@example 171bfd *bfd_openw (const char *filename, const char *target); 172@end example 173@strong{Description}@* 174Create a BFD, associated with file @var{filename}, using the 175file format @var{target}, and return a pointer to it. 176 177Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory}, 178@code{bfd_error_invalid_target}. 179 180A copy of the @var{filename} argument is stored in the newly created 181BFD. It can be accessed via the bfd_get_filename() macro. 182 183@findex bfd_close 184@subsubsection @code{bfd_close} 185@strong{Synopsis} 186@example 187bool bfd_close (bfd *abfd); 188@end example 189@strong{Description}@* 190Close a BFD. If the BFD was open for writing, then pending 191operations are completed and the file written out and closed. 192If the created file is executable, then @code{chmod} is called 193to mark it as such. 194 195All memory attached to the BFD is released. 196 197The file descriptor associated with the BFD is closed (even 198if it was passed in to BFD by @code{bfd_fdopenr}). 199 200@strong{Returns}@* 201@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 202 203@findex bfd_close_all_done 204@subsubsection @code{bfd_close_all_done} 205@strong{Synopsis} 206@example 207bool bfd_close_all_done (bfd *); 208@end example 209@strong{Description}@* 210Close a BFD. Differs from @code{bfd_close} since it does not 211complete any pending operations. This routine would be used 212if the application had just used BFD for swapping and didn't 213want to use any of the writing code. 214 215If the created file is executable, then @code{chmod} is called 216to mark it as such. 217 218All memory attached to the BFD is released. 219 220@strong{Returns}@* 221@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 222 223@findex bfd_create 224@subsubsection @code{bfd_create} 225@strong{Synopsis} 226@example 227bfd *bfd_create (const char *filename, bfd *templ); 228@end example 229@strong{Description}@* 230Create a new BFD in the manner of @code{bfd_openw}, but without 231opening a file. The new BFD takes the target from the target 232used by @var{templ}. The format is always set to @code{bfd_object}. 233 234A copy of the @var{filename} argument is stored in the newly created 235BFD. It can be accessed via the bfd_get_filename() macro. 236 237@findex bfd_make_writable 238@subsubsection @code{bfd_make_writable} 239@strong{Synopsis} 240@example 241bool bfd_make_writable (bfd *abfd); 242@end example 243@strong{Description}@* 244Takes a BFD as created by @code{bfd_create} and converts it 245into one like as returned by @code{bfd_openw}. It does this 246by converting the BFD to BFD_IN_MEMORY. It's assumed that 247you will call @code{bfd_make_readable} on this bfd later. 248 249@strong{Returns}@* 250@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 251 252@findex bfd_make_readable 253@subsubsection @code{bfd_make_readable} 254@strong{Synopsis} 255@example 256bool bfd_make_readable (bfd *abfd); 257@end example 258@strong{Description}@* 259Takes a BFD as created by @code{bfd_create} and 260@code{bfd_make_writable} and converts it into one like as 261returned by @code{bfd_openr}. It does this by writing the 262contents out to the memory buffer, then reversing the 263direction. 264 265@strong{Returns}@* 266@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 267 268@findex bfd_alloc 269@subsubsection @code{bfd_alloc} 270@strong{Synopsis} 271@example 272void *bfd_alloc (bfd *abfd, bfd_size_type wanted); 273@end example 274@strong{Description}@* 275Allocate a block of @var{wanted} bytes of memory attached to 276@code{abfd} and return a pointer to it. 277 278@findex bfd_zalloc 279@subsubsection @code{bfd_zalloc} 280@strong{Synopsis} 281@example 282void *bfd_zalloc (bfd *abfd, bfd_size_type wanted); 283@end example 284@strong{Description}@* 285Allocate a block of @var{wanted} bytes of zeroed memory 286attached to @code{abfd} and return a pointer to it. 287 288@findex bfd_calc_gnu_debuglink_crc32 289@subsubsection @code{bfd_calc_gnu_debuglink_crc32} 290@strong{Synopsis} 291@example 292unsigned long bfd_calc_gnu_debuglink_crc32 293 (unsigned long crc, const unsigned char *buf, bfd_size_type len); 294@end example 295@strong{Description}@* 296Computes a CRC value as used in the .gnu_debuglink section. 297Advances the previously computed @var{crc} value by computing 298and adding in the crc32 for @var{len} bytes of @var{buf}. 299 300@strong{Returns}@* 301Return the updated CRC32 value. 302 303@findex bfd_get_debug_link_info_1 304@subsubsection @code{bfd_get_debug_link_info_1} 305@strong{Synopsis} 306@example 307char *bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out); 308@end example 309@strong{Description}@* 310Extracts the filename and CRC32 value for any separate debug 311information file associated with @var{abfd}. 312 313The @var{crc32_out} parameter is an untyped pointer because 314this routine is used as a @code{get_func_type} function, but it 315is expected to be an unsigned long pointer. 316 317@strong{Returns}@* 318The filename of the associated debug information file, or NULL 319if there is no such file. If the filename was found then the 320contents of @var{crc32_out} are updated to hold the corresponding 321CRC32 value for the file. 322 323The returned filename is allocated with @code{malloc}; freeing 324it is the responsibility of the caller. 325 326@findex bfd_get_debug_link_info 327@subsubsection @code{bfd_get_debug_link_info} 328@strong{Synopsis} 329@example 330char *bfd_get_debug_link_info (bfd *abfd, unsigned long *crc32_out); 331@end example 332@strong{Description}@* 333Extracts the filename and CRC32 value for any separate debug 334information file associated with @var{abfd}. 335 336@strong{Returns}@* 337The filename of the associated debug information file, or NULL 338if there is no such file. If the filename was found then the 339contents of @var{crc32_out} are updated to hold the corresponding 340CRC32 value for the file. 341 342The returned filename is allocated with @code{malloc}; freeing 343it is the responsibility of the caller. 344 345@findex bfd_get_alt_debug_link_info 346@subsubsection @code{bfd_get_alt_debug_link_info} 347@strong{Synopsis} 348@example 349char *bfd_get_alt_debug_link_info (bfd * abfd, 350 bfd_size_type *buildid_len, 351 bfd_byte **buildid_out); 352@end example 353@strong{Description}@* 354Fetch the filename and BuildID value for any alternate debuginfo 355associated with @var{abfd}. Return NULL if no such info found, 356otherwise return filename and update @var{buildid_len} and 357@var{buildid_out}. The returned filename and build_id are 358allocated with @code{malloc}; freeing them is the responsibility 359of the caller. 360 361@findex separate_debug_file_exists 362@subsubsection @code{separate_debug_file_exists} 363@strong{Synopsis} 364@example 365bool separate_debug_file_exists 366 (char *name, void *crc32_p); 367@end example 368@strong{Description}@* 369Checks to see if @var{name} is a file and if its contents 370match @var{crc32}, which is a pointer to an @code{unsigned 371long} containing a CRC32. 372 373The @var{crc32_p} parameter is an untyped pointer because 374this routine is used as a @code{check_func_type} function. 375 376@findex separate_alt_debug_file_exists 377@subsubsection @code{separate_alt_debug_file_exists} 378@strong{Synopsis} 379@example 380bool separate_alt_debug_file_exists 381 (char *name, void *unused); 382@end example 383@strong{Description}@* 384Checks to see if @var{name} is a file. 385 386@findex find_separate_debug_file 387@subsubsection @code{find_separate_debug_file} 388@strong{Synopsis} 389@example 390char *find_separate_debug_file 391 (bfd *abfd, const char *dir, bool include_dirs, 392 get_func_type get, check_func_type check, void *data); 393@end example 394@strong{Description}@* 395Searches for a debug information file corresponding to @var{abfd}. 396 397The name of the separate debug info file is returned by the 398@var{get} function. This function scans various fixed locations 399in the filesystem, including the file tree rooted at @var{dir}. 400If the @var{include_dirs} parameter is true then the directory 401components of @var{abfd}'s filename will be included in the 402searched locations. 403 404@var{data} is passed unmodified to the @var{get} and @var{check} 405functions. It is generally used to implement build-id-like 406matching in the callback functions. 407 408@strong{Returns}@* 409Returns the filename of the first file to be found which 410receives a TRUE result from the @var{check} function. 411Returns NULL if no valid file could be found. 412 413@findex bfd_follow_gnu_debuglink 414@subsubsection @code{bfd_follow_gnu_debuglink} 415@strong{Synopsis} 416@example 417char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir); 418@end example 419@strong{Description}@* 420Takes a BFD and searches it for a .gnu_debuglink section. If this 421section is found, it examines the section for the name and checksum 422of a '.debug' file containing auxiliary debugging information. It 423then searches the filesystem for this .debug file in some standard 424locations, including the directory tree rooted at @var{dir}, and if 425found returns the full filename. 426 427If @var{dir} is NULL, the search will take place starting at 428the current directory. 429 430@strong{Returns}@* 431@code{NULL} on any errors or failure to locate the .debug file, 432otherwise a pointer to a heap-allocated string containing the 433filename. The caller is responsible for freeing this string. 434 435@findex bfd_follow_gnu_debugaltlink 436@subsubsection @code{bfd_follow_gnu_debugaltlink} 437@strong{Synopsis} 438@example 439char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir); 440@end example 441@strong{Description}@* 442Takes a BFD and searches it for a .gnu_debugaltlink section. If this 443section is found, it examines the section for the name of a file 444containing auxiliary debugging information. It then searches the 445filesystem for this file in a set of standard locations, including 446the directory tree rooted at @var{dir}, and if found returns the 447full filename. 448 449If @var{dir} is NULL, the search will take place starting at 450the current directory. 451 452@strong{Returns}@* 453@code{NULL} on any errors or failure to locate the debug file, 454otherwise a pointer to a heap-allocated string containing the 455filename. The caller is responsible for freeing this string. 456 457@findex bfd_create_gnu_debuglink_section 458@subsubsection @code{bfd_create_gnu_debuglink_section} 459@strong{Synopsis} 460@example 461struct bfd_section *bfd_create_gnu_debuglink_section 462 (bfd *abfd, const char *filename); 463@end example 464@strong{Description}@* 465Takes a @var{BFD} and adds a .gnu_debuglink section to it. The 466section is sized to be big enough to contain a link to the specified 467@var{filename}. 468 469@strong{Returns}@* 470A pointer to the new section is returned if all is ok. Otherwise 471@code{NULL} is returned and bfd_error is set. 472 473@findex bfd_fill_in_gnu_debuglink_section 474@subsubsection @code{bfd_fill_in_gnu_debuglink_section} 475@strong{Synopsis} 476@example 477bool bfd_fill_in_gnu_debuglink_section 478 (bfd *abfd, struct bfd_section *sect, const char *filename); 479@end example 480@strong{Description}@* 481Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT} 482and fills in the contents of the section to contain a link to the 483specified @var{filename}. The filename should be relative to the 484current directory. 485 486@strong{Returns}@* 487@code{TRUE} is returned if all is ok. Otherwise @code{FALSE} is returned 488and bfd_error is set. 489 490@findex get_build_id 491@subsubsection @code{get_build_id} 492@strong{Synopsis} 493@example 494struct bfd_build_id * get_build_id (bfd *abfd); 495@end example 496@strong{Description}@* 497Finds the build-id associated with @var{abfd}. If the build-id is 498extracted from the note section then a build-id structure is built 499for it, using memory allocated to @var{abfd}, and this is then 500attached to the @var{abfd}. 501 502@strong{Returns}@* 503Returns a pointer to the build-id structure if a build-id could be 504found. If no build-id is found NULL is returned and error code is 505set. 506 507@findex get_build_id_name 508@subsubsection @code{get_build_id_name} 509@strong{Synopsis} 510@example 511char * get_build_id_name (bfd *abfd, void *build_id_out_p) 512@end example 513@strong{Description}@* 514Searches @var{abfd} for a build-id, and then constructs a pathname 515from it. The path is computed as .build-id/NN/NN+NN.debug where 516NNNN+NN is the build-id value as a hexadecimal string. 517 518@strong{Returns}@* 519Returns the constructed filename or NULL upon error. 520It is the caller's responsibility to free the memory used to hold the 521filename. 522If a filename is returned then the @var{build_id_out_p} 523parameter (which points to a @code{struct bfd_build_id} 524pointer) is set to a pointer to the build_id structure. 525 526@findex check_build_id_file 527@subsubsection @code{check_build_id_file} 528@strong{Synopsis} 529@example 530bool check_build_id_file (char *name, void *buildid_p); 531@end example 532@strong{Description}@* 533Checks to see if @var{name} is a readable file and if its build-id 534matches @var{buildid}. 535 536@strong{Returns}@* 537Returns TRUE if the file exists, is readable, and contains a 538build-id which matches the build-id pointed at by 539@var{build_id_p} (which is really a @code{struct bfd_build_id **}). 540 541@findex bfd_follow_build_id_debuglink 542@subsubsection @code{bfd_follow_build_id_debuglink} 543@strong{Synopsis} 544@example 545char *bfd_follow_build_id_debuglink (bfd *abfd, const char *dir); 546@end example 547@strong{Description}@* 548Takes @var{abfd} and searches it for a .note.gnu.build-id section. 549If this section is found, it extracts the value of the NT_GNU_BUILD_ID 550note, which should be a hexadecimal value @var{NNNN+NN} (for 55132+ hex digits). It then searches the filesystem for a file named 552@var{.build-id/NN/NN+NN.debug} in a set of standard locations, 553including the directory tree rooted at @var{dir}. The filename 554of the first matching file to be found is returned. A matching 555file should contain a .note.gnu.build-id section with the same 556@var{NNNN+NN} note as @var{abfd}, although this check is currently 557not implemented. 558 559If @var{dir} is NULL, the search will take place starting at 560the current directory. 561 562@strong{Returns}@* 563@code{NULL} on any errors or failure to locate the debug file, 564otherwise a pointer to a heap-allocated string containing the 565filename. The caller is responsible for freeing this string. 566 567@findex bfd_set_filename 568@subsubsection @code{bfd_set_filename} 569@strong{Synopsis} 570@example 571const char *bfd_set_filename (bfd *abfd, const char *filename); 572@end example 573@strong{Description}@* 574Set the filename of @var{abfd}, copying the FILENAME parameter to 575bfd_alloc'd memory owned by @var{abfd}. Returns a pointer the 576newly allocated name, or NULL if the allocation failed. 577 578