opncls.texi revision 1.1.1.8
1@section Opening and closing BFDs 2 3 4@subsection Functions for opening and closing 5 6 7@findex _bfd_new_bfd 8@subsubsection @code{_bfd_new_bfd} 9@deftypefn {Function} bfd *_bfd_new_bfd (void); 10Return a new BFD. All BFD's are allocated through this routine. 11 12@end deftypefn 13@findex _bfd_new_bfd_contained_in 14@subsubsection @code{_bfd_new_bfd_contained_in} 15@deftypefn {Function} bfd *_bfd_new_bfd_contained_in (bfd *); 16Allocate a new BFD as a member of archive OBFD. 17 18@end deftypefn 19@findex _bfd_free_cached_info 20@subsubsection @code{_bfd_free_cached_info} 21@deftypefn {Function} bool _bfd_free_cached_info (bfd *); 22Free objalloc memory. 23 24@end deftypefn 25@findex bfd_fopen 26@subsubsection @code{bfd_fopen} 27@deftypefn {Function} bfd *bfd_fopen (const char *filename, const char *target, const char *mode, int fd); 28Open the file @var{filename} with the target @var{target}. 29Return a pointer to the created BFD. If @var{fd} is not -1, 30then @code{fdopen} is used to open the file; otherwise, @code{fopen} 31is used. @var{mode} is passed directly to @code{fopen} or 32@code{fdopen}. 33 34Calls @code{bfd_find_target}, so @var{target} is interpreted as by 35that function. 36 37The new BFD is marked as cacheable iff @var{fd} is -1. 38 39If @code{NULL} is returned then an error has occured. Possible errors 40are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or 41@code{system_call} error. 42 43On error, @var{fd} is always closed. 44 45A copy of the @var{filename} argument is stored in the newly created 46BFD. It can be accessed via the bfd_get_filename() macro. 47 48@end deftypefn 49@findex bfd_openr 50@subsubsection @code{bfd_openr} 51@deftypefn {Function} bfd *bfd_openr (const char *filename, const char *target); 52Open the file @var{filename} (using @code{fopen}) with the target 53@var{target}. Return a pointer to the created BFD. 54 55Calls @code{bfd_find_target}, so @var{target} is interpreted as by 56that function. 57 58If @code{NULL} is returned then an error has occured. Possible errors 59are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or 60@code{system_call} error. 61 62A copy of the @var{filename} argument is stored in the newly created 63BFD. It can be accessed via the bfd_get_filename() macro. 64 65@end deftypefn 66@findex bfd_fdopenr 67@subsubsection @code{bfd_fdopenr} 68@deftypefn {Function} bfd *bfd_fdopenr (const char *filename, const char *target, int fd); 69@code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to 70@code{fopen}. It opens a BFD on a file already described by the 71@var{fd} supplied. 72 73When the file is later @code{bfd_close}d, the file descriptor will 74be closed. If the caller desires that this file descriptor be 75cached by BFD (opened as needed, closed as needed to free 76descriptors for other opens), with the supplied @var{fd} used as 77an initial file descriptor (but subject to closure at any time), 78call bfd_set_cacheable(bfd, 1) on the returned BFD. The default 79is to assume no caching; the file descriptor will remain open 80until @code{bfd_close}, and will not be affected by BFD operations 81on other files. 82 83Possible errors are @code{bfd_error_no_memory}, 84@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. 85 86On error, @var{fd} is closed. 87 88A copy of the @var{filename} argument is stored in the newly created 89BFD. It can be accessed via the bfd_get_filename() macro. 90 91@end deftypefn 92@findex bfd_fdopenw 93@subsubsection @code{bfd_fdopenw} 94@deftypefn {Function} bfd *bfd_fdopenw (const char *filename, const char *target, int fd); 95@code{bfd_fdopenw} is exactly like @code{bfd_fdopenr} with the exception that 96the resulting BFD is suitable for output. 97 98@end deftypefn 99@findex bfd_openstreamr 100@subsubsection @code{bfd_openstreamr} 101@deftypefn {Function} bfd *bfd_openstreamr (const char * filename, const char * target, void * stream); 102Open a BFD for read access on an existing stdio stream. When 103the BFD is passed to @code{bfd_close}, the stream will be closed. 104 105A copy of the @var{filename} argument is stored in the newly created 106BFD. It can be accessed via the bfd_get_filename() macro. 107 108@end deftypefn 109@findex bfd_openr_iovec 110@subsubsection @code{bfd_openr_iovec} 111@deftypefn {Function} bfd *bfd_openr_iovec (const char *filename, const char *target, void *(*open_func) (struct bfd *nbfd, void *open_closure), void *open_closure, file_ptr (*pread_func) (struct bfd *nbfd, void *stream, void *buf, file_ptr nbytes, file_ptr offset), int (*close_func) (struct bfd *nbfd, void *stream), int (*stat_func) (struct bfd *abfd, void *stream, struct stat *sb)); 112Create and return a BFD backed by a read-only @var{stream}. 113The @var{stream} is created using @var{open_func}, accessed using 114@var{pread_func} and destroyed using @var{close_func}. 115 116Calls @code{bfd_find_target}, so @var{target} is interpreted as by 117that function. 118 119Calls @var{open_func} (which can call @code{bfd_zalloc} and 120@code{bfd_get_filename}) to obtain the read-only stream backing 121the BFD. @var{open_func} either succeeds returning the 122non-@code{NULL} @var{stream}, or fails returning @code{NULL} 123(setting @code{bfd_error}). 124 125Calls @var{pread_func} to request @var{nbytes} of data from 126@var{stream} starting at @var{offset} (e.g., via a call to 127@code{bfd_read}). @var{pread_func} either succeeds returning the 128number of bytes read (which can be less than @var{nbytes} when 129end-of-file), or fails returning -1 (setting @code{bfd_error}). 130 131Calls @var{close_func} when the BFD is later closed using 132@code{bfd_close}. @var{close_func} either succeeds returning 0, or 133fails returning -1 (setting @code{bfd_error}). 134 135Calls @var{stat_func} to fill in a stat structure for bfd_stat, 136bfd_get_size, and bfd_get_mtime calls. @var{stat_func} returns 0 137on success, or returns -1 on failure (setting @code{bfd_error}). 138 139If @code{bfd_openr_iovec} returns @code{NULL} then an error has 140occurred. Possible errors are @code{bfd_error_no_memory}, 141@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. 142 143A copy of the @var{filename} argument is stored in the newly created 144BFD. It can be accessed via the bfd_get_filename() macro. 145 146@end deftypefn 147@findex bfd_openw 148@subsubsection @code{bfd_openw} 149@deftypefn {Function} bfd *bfd_openw (const char *filename, const char *target); 150Create a BFD, associated with file @var{filename}, using the 151file format @var{target}, and return a pointer to it. 152 153Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory}, 154@code{bfd_error_invalid_target}. 155 156A copy of the @var{filename} argument is stored in the newly created 157BFD. It can be accessed via the bfd_get_filename() macro. 158 159@end deftypefn 160@findex bfd_elf_bfd_from_remote_memory 161@subsubsection @code{bfd_elf_bfd_from_remote_memory} 162@deftypefn {Function} bfd *bfd_elf_bfd_from_remote_memory (bfd *templ, bfd_vma ehdr_vma, bfd_size_type size, bfd_vma *loadbasep, int (*target_read_memory) (bfd_vma vma, bfd_byte *myaddr, bfd_size_type len)); 163Create a new BFD as if by bfd_openr. Rather than opening a 164file, reconstruct an ELF file by reading the segments out of 165remote memory based on the ELF file header at EHDR_VMA and the 166ELF program headers it points to. If non-zero, SIZE is the 167known extent of the object. If not null, *LOADBASEP is filled 168in with the difference between the VMAs from which the 169segments were read, and the VMAs the file headers (and hence 170BFD's idea of each section's VMA) put them at. 171 172The function TARGET_READ_MEMORY is called to copy LEN bytes 173from the remote memory at target address VMA into the local 174buffer at MYADDR; it should return zero on success or an 175errno code on failure. TEMPL must be a BFD for an ELF 176target with the word size and byte order found in the remote 177memory. 178 179@end deftypefn 180@findex bfd_close 181@subsubsection @code{bfd_close} 182@deftypefn {Function} bool bfd_close (bfd *abfd); 183Close a BFD. If the BFD was open for writing, then pending 184operations are completed and the file written out and closed. 185If the created file is executable, then @code{chmod} is called 186to mark it as such. 187 188All memory attached to the BFD is released. 189 190The file descriptor associated with the BFD is closed (even 191if it was passed in to BFD by @code{bfd_fdopenr}). 192 193@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 194 195@end deftypefn 196@findex bfd_close_all_done 197@subsubsection @code{bfd_close_all_done} 198@deftypefn {Function} bool bfd_close_all_done (bfd *); 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@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 210 211@end deftypefn 212@findex bfd_create 213@subsubsection @code{bfd_create} 214@deftypefn {Function} bfd *bfd_create (const char *filename, bfd *templ); 215Create a new BFD in the manner of @code{bfd_openw}, but without 216opening a file. The new BFD takes the target from the target 217used by @var{templ}. The format is always set to @code{bfd_object}. 218 219A copy of the @var{filename} argument is stored in the newly created 220BFD. It can be accessed via the bfd_get_filename() macro. 221 222@end deftypefn 223@findex bfd_make_writable 224@subsubsection @code{bfd_make_writable} 225@deftypefn {Function} bool bfd_make_writable (bfd *abfd); 226Takes a BFD as created by @code{bfd_create} and converts it 227into one like as returned by @code{bfd_openw}. It does this 228by converting the BFD to BFD_IN_MEMORY. It's assumed that 229you will call @code{bfd_make_readable} on this bfd later. 230 231@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 232 233@end deftypefn 234@findex bfd_make_readable 235@subsubsection @code{bfd_make_readable} 236@deftypefn {Function} bool bfd_make_readable (bfd *abfd); 237Takes a BFD as created by @code{bfd_create} and 238@code{bfd_make_writable} and converts it into one like as 239returned by @code{bfd_openr}. It does this by writing the 240contents out to the memory buffer, then reversing the 241direction. 242 243@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. 244 245@end deftypefn 246@findex bfd_calc_gnu_debuglink_crc32 247@subsubsection @code{bfd_calc_gnu_debuglink_crc32} 248@deftypefn {Function} uint32_t bfd_calc_gnu_debuglink_crc32 (uint32_t crc, const bfd_byte *buf, bfd_size_type len); 249Computes a CRC value as used in the .gnu_debuglink section. 250Advances the previously computed @var{crc} value by computing 251and adding in the crc32 for @var{len} bytes of @var{buf}. 252 253Return the updated CRC32 value. 254 255@end deftypefn 256@findex bfd_get_debug_link_info 257@subsubsection @code{bfd_get_debug_link_info} 258@deftypefn {Function} char *bfd_get_debug_link_info (bfd *abfd, uint32_t *crc32_out); 259Extracts the filename and CRC32 value for any separate debug 260information file associated with @var{abfd}. 261 262Returns the filename of the associated debug information file, 263or NULL if there is no such file. If the filename was found 264then the contents of @var{crc32_out} are updated to hold the 265corresponding CRC32 value for the file. 266 267The returned filename is allocated with @code{malloc}; freeing 268it is the responsibility of the caller. 269 270@end deftypefn 271@findex bfd_get_alt_debug_link_info 272@subsubsection @code{bfd_get_alt_debug_link_info} 273@deftypefn {Function} char *bfd_get_alt_debug_link_info (bfd * abfd, bfd_size_type *buildid_len, bfd_byte **buildid_out); 274Fetch the filename and BuildID value for any alternate debuginfo 275associated with @var{abfd}. Return NULL if no such info found, 276otherwise return filename and update @var{buildid_len} and 277@var{buildid_out}. The returned filename and build_id are 278allocated with @code{malloc}; freeing them is the responsibility 279of the caller. 280 281@end deftypefn 282@findex bfd_follow_gnu_debuglink 283@subsubsection @code{bfd_follow_gnu_debuglink} 284@deftypefn {Function} char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir); 285Takes a BFD and searches it for a .gnu_debuglink section. If this 286section is found, it examines the section for the name and checksum 287of a '.debug' file containing auxiliary debugging information. It 288then searches the filesystem for this .debug file in some standard 289locations, including the directory tree rooted at @var{dir}, and if 290found returns the full filename. 291 292If @var{dir} is NULL, the search will take place starting at 293the current directory. 294 295Returns @code{NULL} on any errors or failure to locate the .debug 296file, otherwise a pointer to a heap-allocated string 297containing the filename. The caller is responsible for 298freeing this string. 299 300@end deftypefn 301@findex bfd_follow_gnu_debugaltlink 302@subsubsection @code{bfd_follow_gnu_debugaltlink} 303@deftypefn {Function} char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir); 304Takes a BFD and searches it for a .gnu_debugaltlink section. If this 305section is found, it examines the section for the name of a file 306containing auxiliary debugging information. It then searches the 307filesystem for this file in a set of standard locations, including 308the directory tree rooted at @var{dir}, and if found returns the 309full filename. 310 311If @var{dir} is NULL, the search will take place starting at 312the current directory. 313 314Returns @code{NULL} on any errors or failure to locate the debug 315file, otherwise a pointer to a heap-allocated string 316containing the filename. The caller is responsible for 317freeing this string. 318 319@end deftypefn 320@findex bfd_create_gnu_debuglink_section 321@subsubsection @code{bfd_create_gnu_debuglink_section} 322@deftypefn {Function} struct bfd_section *bfd_create_gnu_debuglink_section (bfd *abfd, const char *filename); 323Takes a @var{BFD} and adds a .gnu_debuglink section to it. The 324section is sized to be big enough to contain a link to the specified 325@var{filename}. 326 327A pointer to the new section is returned if all is ok. Otherwise 328@code{NULL} is returned and bfd_error is set. 329 330@end deftypefn 331@findex bfd_fill_in_gnu_debuglink_section 332@subsubsection @code{bfd_fill_in_gnu_debuglink_section} 333@deftypefn {Function} bool bfd_fill_in_gnu_debuglink_section (bfd *abfd, struct bfd_section *sect, const char *filename); 334Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT} 335and fills in the contents of the section to contain a link to the 336specified @var{filename}. The filename should be absolute or 337relative to the current directory. 338 339@code{TRUE} is returned if all is ok. Otherwise @code{FALSE} is returned 340and bfd_error is set. 341 342@end deftypefn 343@findex bfd_follow_build_id_debuglink 344@subsubsection @code{bfd_follow_build_id_debuglink} 345@deftypefn {Function} char *bfd_follow_build_id_debuglink (bfd *abfd, const char *dir); 346Takes @var{abfd} and searches it for a .note.gnu.build-id section. 347If this section is found, it extracts the value of the NT_GNU_BUILD_ID 348note, which should be a hexadecimal value @var{NNNN+NN} (for 34932+ hex digits). It then searches the filesystem for a file named 350@var{.build-id/NN/NN+NN.debug} in a set of standard locations, 351including the directory tree rooted at @var{dir}. The filename 352of the first matching file to be found is returned. A matching 353file should contain a .note.gnu.build-id section with the same 354@var{NNNN+NN} note as @var{abfd}, although this check is currently 355not implemented. 356 357If @var{dir} is NULL, the search will take place starting at 358the current directory. 359 360Returns @code{NULL} on any errors or failure to locate the debug 361file, otherwise a pointer to a heap-allocated string 362containing the filename. The caller is responsible for 363freeing this string. 364 365@end deftypefn 366@findex bfd_set_filename 367@subsubsection @code{bfd_set_filename} 368@deftypefn {Function} const char *bfd_set_filename (bfd *abfd, const char *filename); 369Set the filename of @var{abfd}, copying the FILENAME parameter to 370bfd_alloc'd memory owned by @var{abfd}. Returns a pointer the 371newly allocated name, or NULL if the allocation failed. 372 373@end deftypefn 374