opncls.texi revision 1.1.1.1
1@section Opening and closing BFDs 2 3 4@subsection Functions for opening and closing 5 6 7@findex bfd_fopen 8@subsubsection @code{bfd_fopen} 9@strong{Synopsis} 10@example 11bfd *bfd_fopen (const char *filename, const char *target, 12 const char *mode, int fd); 13@end example 14@strong{Description}@* 15Open the file @var{filename} with the target @var{target}. 16Return a pointer to the created BFD. If @var{fd} is not -1, 17then @code{fdopen} is used to open the file; otherwise, @code{fopen} 18is used. @var{mode} is passed directly to @code{fopen} or 19@code{fdopen}. 20 21Calls @code{bfd_find_target}, so @var{target} is interpreted as by 22that function. 23 24The new BFD is marked as cacheable iff @var{fd} is -1. 25 26If @code{NULL} is returned then an error has occured. Possible errors 27are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or 28@code{system_call} error. 29 30@findex bfd_openr 31@subsubsection @code{bfd_openr} 32@strong{Synopsis} 33@example 34bfd *bfd_openr (const char *filename, const char *target); 35@end example 36@strong{Description}@* 37Open the file @var{filename} (using @code{fopen}) with the target 38@var{target}. Return a pointer to the created BFD. 39 40Calls @code{bfd_find_target}, so @var{target} is interpreted as by 41that function. 42 43If @code{NULL} is returned then an error has occured. Possible errors 44are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or 45@code{system_call} error. 46 47@findex bfd_fdopenr 48@subsubsection @code{bfd_fdopenr} 49@strong{Synopsis} 50@example 51bfd *bfd_fdopenr (const char *filename, const char *target, int fd); 52@end example 53@strong{Description}@* 54@code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to 55@code{fopen}. It opens a BFD on a file already described by the 56@var{fd} supplied. 57 58When the file is later @code{bfd_close}d, the file descriptor will 59be closed. If the caller desires that this file descriptor be 60cached by BFD (opened as needed, closed as needed to free 61descriptors for other opens), with the supplied @var{fd} used as 62an initial file descriptor (but subject to closure at any time), 63call bfd_set_cacheable(bfd, 1) on the returned BFD. The default 64is to assume no caching; the file descriptor will remain open 65until @code{bfd_close}, and will not be affected by BFD operations 66on other files. 67 68Possible errors are @code{bfd_error_no_memory}, 69@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. 70 71@findex bfd_openstreamr 72@subsubsection @code{bfd_openstreamr} 73@strong{Synopsis} 74@example 75bfd *bfd_openstreamr (const char *, const char *, void *); 76@end example 77@strong{Description}@* 78Open a BFD for read access on an existing stdio stream. When 79the BFD is passed to @code{bfd_close}, the stream will be closed. 80 81@findex bfd_openr_iovec 82@subsubsection @code{bfd_openr_iovec} 83@strong{Synopsis} 84@example 85bfd *bfd_openr_iovec (const char *filename, const char *target, 86 void *(*open) (struct bfd *nbfd, 87 void *open_closure), 88 void *open_closure, 89 file_ptr (*pread) (struct bfd *nbfd, 90 void *stream, 91 void *buf, 92 file_ptr nbytes, 93 file_ptr offset), 94 int (*close) (struct bfd *nbfd, 95 void *stream), 96 int (*stat) (struct bfd *abfd, 97 void *stream, 98 struct stat *sb)); 99@end example 100@strong{Description}@* 101Create and return a BFD backed by a read-only @var{stream}. 102The @var{stream} is created using @var{open}, accessed using 103@var{pread} and destroyed using @var{close}. 104 105Calls @code{bfd_find_target}, so @var{target} is interpreted as by 106that function. 107 108Calls @var{open} (which can call @code{bfd_zalloc} and 109@code{bfd_get_filename}) to obtain the read-only stream backing 110the BFD. @var{open} either succeeds returning the 111non-@code{NULL} @var{stream}, or fails returning @code{NULL} 112(setting @code{bfd_error}). 113 114Calls @var{pread} to request @var{nbytes} of data from 115@var{stream} starting at @var{offset} (e.g., via a call to 116@code{bfd_read}). @var{pread} either succeeds returning the 117number of bytes read (which can be less than @var{nbytes} when 118end-of-file), or fails returning -1 (setting @code{bfd_error}). 119 120Calls @var{close} when the BFD is later closed using 121@code{bfd_close}. @var{close} either succeeds returning 0, or 122fails returning -1 (setting @code{bfd_error}). 123 124Calls @var{stat} to fill in a stat structure for bfd_stat, 125bfd_get_size, and bfd_get_mtime calls. @var{stat} returns 0 126on success, or returns -1 on failure (setting @code{bfd_error}). 127 128If @code{bfd_openr_iovec} returns @code{NULL} then an error has 129occurred. Possible errors are @code{bfd_error_no_memory}, 130@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. 131 132@findex bfd_openw 133@subsubsection @code{bfd_openw} 134@strong{Synopsis} 135@example 136bfd *bfd_openw (const char *filename, const char *target); 137@end example 138@strong{Description}@* 139Create a BFD, associated with file @var{filename}, using the 140file format @var{target}, and return a pointer to it. 141 142Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory}, 143@code{bfd_error_invalid_target}. 144 145@findex bfd_close 146@subsubsection @code{bfd_close} 147@strong{Synopsis} 148@example 149bfd_boolean bfd_close (bfd *abfd); 150@end example 151@strong{Description}@* 152Close a BFD. If the BFD was open for writing, then pending 153operations are completed and the file written out and closed. 154If the created file is executable, then @code{chmod} is called 155to mark it as such. 156 157All memory attached to the BFD is released. 158 159The file descriptor associated with the BFD is closed (even 160if it was passed in to BFD by @code{bfd_fdopenr}). 161 162@strong{Returns}@* 163@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 164 165@findex bfd_close_all_done 166@subsubsection @code{bfd_close_all_done} 167@strong{Synopsis} 168@example 169bfd_boolean bfd_close_all_done (bfd *); 170@end example 171@strong{Description}@* 172Close a BFD. Differs from @code{bfd_close} since it does not 173complete any pending operations. This routine would be used 174if the application had just used BFD for swapping and didn't 175want to use any of the writing code. 176 177If the created file is executable, then @code{chmod} is called 178to mark it as such. 179 180All memory attached to the BFD is released. 181 182@strong{Returns}@* 183@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 184 185@findex bfd_create 186@subsubsection @code{bfd_create} 187@strong{Synopsis} 188@example 189bfd *bfd_create (const char *filename, bfd *templ); 190@end example 191@strong{Description}@* 192Create a new BFD in the manner of @code{bfd_openw}, but without 193opening a file. The new BFD takes the target from the target 194used by @var{template}. The format is always set to @code{bfd_object}. 195 196@findex bfd_make_writable 197@subsubsection @code{bfd_make_writable} 198@strong{Synopsis} 199@example 200bfd_boolean bfd_make_writable (bfd *abfd); 201@end example 202@strong{Description}@* 203Takes a BFD as created by @code{bfd_create} and converts it 204into one like as returned by @code{bfd_openw}. It does this 205by converting the BFD to BFD_IN_MEMORY. It's assumed that 206you will call @code{bfd_make_readable} on this bfd later. 207 208@strong{Returns}@* 209@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 210 211@findex bfd_make_readable 212@subsubsection @code{bfd_make_readable} 213@strong{Synopsis} 214@example 215bfd_boolean bfd_make_readable (bfd *abfd); 216@end example 217@strong{Description}@* 218Takes a BFD as created by @code{bfd_create} and 219@code{bfd_make_writable} and converts it into one like as 220returned by @code{bfd_openr}. It does this by writing the 221contents out to the memory buffer, then reversing the 222direction. 223 224@strong{Returns}@* 225@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 226 227@findex bfd_alloc 228@subsubsection @code{bfd_alloc} 229@strong{Synopsis} 230@example 231void *bfd_alloc (bfd *abfd, bfd_size_type wanted); 232@end example 233@strong{Description}@* 234Allocate a block of @var{wanted} bytes of memory attached to 235@code{abfd} and return a pointer to it. 236 237@findex bfd_alloc2 238@subsubsection @code{bfd_alloc2} 239@strong{Synopsis} 240@example 241void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size); 242@end example 243@strong{Description}@* 244Allocate a block of @var{nmemb} elements of @var{size} bytes each 245of memory attached to @code{abfd} and return a pointer to it. 246 247@findex bfd_zalloc 248@subsubsection @code{bfd_zalloc} 249@strong{Synopsis} 250@example 251void *bfd_zalloc (bfd *abfd, bfd_size_type wanted); 252@end example 253@strong{Description}@* 254Allocate a block of @var{wanted} bytes of zeroed memory 255attached to @code{abfd} and return a pointer to it. 256 257@findex bfd_zalloc2 258@subsubsection @code{bfd_zalloc2} 259@strong{Synopsis} 260@example 261void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size); 262@end example 263@strong{Description}@* 264Allocate a block of @var{nmemb} elements of @var{size} bytes each 265of zeroed memory attached to @code{abfd} and return a pointer to it. 266 267@findex bfd_calc_gnu_debuglink_crc32 268@subsubsection @code{bfd_calc_gnu_debuglink_crc32} 269@strong{Synopsis} 270@example 271unsigned long bfd_calc_gnu_debuglink_crc32 272 (unsigned long crc, const unsigned char *buf, bfd_size_type len); 273@end example 274@strong{Description}@* 275Computes a CRC value as used in the .gnu_debuglink section. 276Advances the previously computed @var{crc} value by computing 277and adding in the crc32 for @var{len} bytes of @var{buf}. 278 279@strong{Returns}@* 280Return the updated CRC32 value. 281 282@findex get_debug_link_info 283@subsubsection @code{get_debug_link_info} 284@strong{Synopsis} 285@example 286char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out); 287@end example 288@strong{Description}@* 289fetch the filename and CRC32 value for any separate debuginfo 290associated with @var{abfd}. Return NULL if no such info found, 291otherwise return filename and update @var{crc32_out}. 292 293@findex separate_debug_file_exists 294@subsubsection @code{separate_debug_file_exists} 295@strong{Synopsis} 296@example 297bfd_boolean separate_debug_file_exists 298 (char *name, unsigned long crc32); 299@end example 300@strong{Description}@* 301Checks to see if @var{name} is a file and if its contents 302match @var{crc32}. 303 304@findex find_separate_debug_file 305@subsubsection @code{find_separate_debug_file} 306@strong{Synopsis} 307@example 308char *find_separate_debug_file (bfd *abfd); 309@end example 310@strong{Description}@* 311Searches @var{abfd} for a reference to separate debugging 312information, scans various locations in the filesystem, including 313the file tree rooted at @var{debug_file_directory}, and returns a 314filename of such debugging information if the file is found and has 315matching CRC32. Returns NULL if no reference to debugging file 316exists, or file cannot be found. 317 318@findex bfd_follow_gnu_debuglink 319@subsubsection @code{bfd_follow_gnu_debuglink} 320@strong{Synopsis} 321@example 322char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir); 323@end example 324@strong{Description}@* 325Takes a BFD and searches it for a .gnu_debuglink section. If this 326section is found, it examines the section for the name and checksum 327of a '.debug' file containing auxiliary debugging information. It 328then searches the filesystem for this .debug file in some standard 329locations, including the directory tree rooted at @var{dir}, and if 330found returns the full filename. 331 332If @var{dir} is NULL, it will search a default path configured into 333libbfd at build time. [XXX this feature is not currently 334implemented]. 335 336@strong{Returns}@* 337@code{NULL} on any errors or failure to locate the .debug file, 338otherwise a pointer to a heap-allocated string containing the 339filename. The caller is responsible for freeing this string. 340 341@findex bfd_create_gnu_debuglink_section 342@subsubsection @code{bfd_create_gnu_debuglink_section} 343@strong{Synopsis} 344@example 345struct bfd_section *bfd_create_gnu_debuglink_section 346 (bfd *abfd, const char *filename); 347@end example 348@strong{Description}@* 349Takes a @var{BFD} and adds a .gnu_debuglink section to it. The section is sized 350to be big enough to contain a link to the specified @var{filename}. 351 352@strong{Returns}@* 353A pointer to the new section is returned if all is ok. Otherwise @code{NULL} is 354returned and bfd_error is set. 355 356@findex bfd_fill_in_gnu_debuglink_section 357@subsubsection @code{bfd_fill_in_gnu_debuglink_section} 358@strong{Synopsis} 359@example 360bfd_boolean bfd_fill_in_gnu_debuglink_section 361 (bfd *abfd, struct bfd_section *sect, const char *filename); 362@end example 363@strong{Description}@* 364Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT} 365and fills in the contents of the section to contain a link to the 366specified @var{filename}. The filename should be relative to the 367current directory. 368 369@strong{Returns}@* 370@code{TRUE} is returned if all is ok. Otherwise @code{FALSE} is returned 371and bfd_error is set. 372 373