opncls.texi revision 1.1.1.4
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 crc32); 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 (bfd *abfd); 368@end example 369@strong{Description}@* 370Searches @var{abfd} for a section called @var{section_name} which 371is expected to contain a reference to a file containing separate 372debugging information. The function scans various locations in 373the filesystem, including the file tree rooted at 374@var{debug_file_directory}, and returns the first matching 375filename that it finds. If @var{check_crc} is TRUE then the 376contents of the file must also match the CRC value contained in 377@var{section_name}. Returns NULL if no valid file could be found. 378 379@findex bfd_follow_gnu_debuglink 380@subsubsection @code{bfd_follow_gnu_debuglink} 381@strong{Synopsis} 382@example 383char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir); 384@end example 385@strong{Description}@* 386Takes a BFD and searches it for a .gnu_debuglink section. If this 387section is found, it examines the section for the name and checksum 388of a '.debug' file containing auxiliary debugging information. It 389then searches the filesystem for this .debug file in some standard 390locations, including the directory tree rooted at @var{dir}, and if 391found returns the full filename. 392 393If @var{dir} is NULL, it will search a default path configured into 394libbfd at build time. [XXX this feature is not currently 395implemented]. 396 397@strong{Returns}@* 398@code{NULL} on any errors or failure to locate the .debug file, 399otherwise a pointer to a heap-allocated string containing the 400filename. The caller is responsible for freeing this string. 401 402@findex bfd_follow_gnu_debugaltlink 403@subsubsection @code{bfd_follow_gnu_debugaltlink} 404@strong{Synopsis} 405@example 406char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir); 407@end example 408@strong{Description}@* 409Takes a BFD and searches it for a .gnu_debugaltlink section. If this 410section is found, it examines the section for the name of a file 411containing auxiliary debugging information. It then searches the 412filesystem for this file in a set of standard locations, including 413the directory tree rooted at @var{dir}, and if found returns the 414full filename. 415 416If @var{dir} is NULL, it will search a default path configured into 417libbfd at build time. [FIXME: This feature is not currently 418implemented]. 419 420@strong{Returns}@* 421@code{NULL} on any errors or failure to locate the debug file, 422otherwise a pointer to a heap-allocated string containing the 423filename. The caller is responsible for freeing this string. 424 425@findex bfd_create_gnu_debuglink_section 426@subsubsection @code{bfd_create_gnu_debuglink_section} 427@strong{Synopsis} 428@example 429struct bfd_section *bfd_create_gnu_debuglink_section 430 (bfd *abfd, const char *filename); 431@end example 432@strong{Description}@* 433Takes a @var{BFD} and adds a .gnu_debuglink section to it. The section is sized 434to be big enough to contain a link to the specified @var{filename}. 435 436@strong{Returns}@* 437A pointer to the new section is returned if all is ok. Otherwise @code{NULL} is 438returned and bfd_error is set. 439 440@findex bfd_fill_in_gnu_debuglink_section 441@subsubsection @code{bfd_fill_in_gnu_debuglink_section} 442@strong{Synopsis} 443@example 444bfd_boolean bfd_fill_in_gnu_debuglink_section 445 (bfd *abfd, struct bfd_section *sect, const char *filename); 446@end example 447@strong{Description}@* 448Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT} 449and fills in the contents of the section to contain a link to the 450specified @var{filename}. The filename should be relative to the 451current directory. 452 453@strong{Returns}@* 454@code{TRUE} is returned if all is ok. Otherwise @code{FALSE} is returned 455and bfd_error is set. 456 457