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