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