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