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