3 /* Set to N to open the next N BFDs using an alternate id space. */
4 extern unsigned int bfd_use_reserved_id;
6 @section Opening and closing BFDs
9 @subsection Functions for opening and closing
13 @subsubsection @code{bfd_fopen}
16 bfd *bfd_fopen (const char *filename, const char *target,
17 const char *mode, int fd);
19 @strong{Description}@*
20 Open the file @var{filename} with the target @var{target}.
21 Return a pointer to the created BFD. If @var{fd} is not -1,
22 then @code{fdopen} is used to open the file; otherwise, @code{fopen}
23 is used. @var{mode} is passed directly to @code{fopen} or
26 Calls @code{bfd_find_target}, so @var{target} is interpreted as by
29 The new BFD is marked as cacheable iff @var{fd} is -1.
31 If @code{NULL} is returned then an error has occured. Possible errors
32 are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
33 @code{system_call} error.
35 On error, @var{fd} is always closed.
37 A copy of the @var{filename} argument is stored in the newly created
38 BFD. It can be accessed via the bfd_get_filename() macro.
41 @subsubsection @code{bfd_openr}
44 bfd *bfd_openr (const char *filename, const char *target);
46 @strong{Description}@*
47 Open the file @var{filename} (using @code{fopen}) with the target
48 @var{target}. Return a pointer to the created BFD.
50 Calls @code{bfd_find_target}, so @var{target} is interpreted as by
53 If @code{NULL} is returned then an error has occured. Possible errors
54 are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
55 @code{system_call} error.
57 A copy of the @var{filename} argument is stored in the newly created
58 BFD. It can be accessed via the bfd_get_filename() macro.
61 @subsubsection @code{bfd_fdopenr}
64 bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
66 @strong{Description}@*
67 @code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to
68 @code{fopen}. It opens a BFD on a file already described by the
71 When the file is later @code{bfd_close}d, the file descriptor will
72 be closed. If the caller desires that this file descriptor be
73 cached by BFD (opened as needed, closed as needed to free
74 descriptors for other opens), with the supplied @var{fd} used as
75 an initial file descriptor (but subject to closure at any time),
76 call bfd_set_cacheable(bfd, 1) on the returned BFD. The default
77 is to assume no caching; the file descriptor will remain open
78 until @code{bfd_close}, and will not be affected by BFD operations
81 Possible errors are @code{bfd_error_no_memory},
82 @code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
84 On error, @var{fd} is closed.
86 A copy of the @var{filename} argument is stored in the newly created
87 BFD. It can be accessed via the bfd_get_filename() macro.
89 @findex bfd_openstreamr
90 @subsubsection @code{bfd_openstreamr}
93 bfd *bfd_openstreamr (const char * filename, const char * target, void * stream);
95 @strong{Description}@*
96 Open a BFD for read access on an existing stdio stream. When
97 the BFD is passed to @code{bfd_close}, the stream will be closed.
99 A copy of the @var{filename} argument is stored in the newly created
100 BFD. It can be accessed via the bfd_get_filename() macro.
102 @findex bfd_openr_iovec
103 @subsubsection @code{bfd_openr_iovec}
106 bfd *bfd_openr_iovec (const char *filename, const char *target,
107 void *(*open_func) (struct bfd *nbfd,
110 file_ptr (*pread_func) (struct bfd *nbfd,
115 int (*close_func) (struct bfd *nbfd,
117 int (*stat_func) (struct bfd *abfd,
121 @strong{Description}@*
122 Create and return a BFD backed by a read-only @var{stream}.
123 The @var{stream} is created using @var{open_func}, accessed using
124 @var{pread_func} and destroyed using @var{close_func}.
126 Calls @code{bfd_find_target}, so @var{target} is interpreted as by
129 Calls @var{open_func} (which can call @code{bfd_zalloc} and
130 @code{bfd_get_filename}) to obtain the read-only stream backing
131 the BFD. @var{open_func} either succeeds returning the
132 non-@code{NULL} @var{stream}, or fails returning @code{NULL}
133 (setting @code{bfd_error}).
135 Calls @var{pread_func} to request @var{nbytes} of data from
136 @var{stream} starting at @var{offset} (e.g., via a call to
137 @code{bfd_read}). @var{pread_func} either succeeds returning the
138 number of bytes read (which can be less than @var{nbytes} when
139 end-of-file), or fails returning -1 (setting @code{bfd_error}).
141 Calls @var{close_func} when the BFD is later closed using
142 @code{bfd_close}. @var{close_func} either succeeds returning 0, or
143 fails returning -1 (setting @code{bfd_error}).
145 Calls @var{stat_func} to fill in a stat structure for bfd_stat,
146 bfd_get_size, and bfd_get_mtime calls. @var{stat_func} returns 0
147 on success, or returns -1 on failure (setting @code{bfd_error}).
149 If @code{bfd_openr_iovec} returns @code{NULL} then an error has
150 occurred. Possible errors are @code{bfd_error_no_memory},
151 @code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
153 A copy of the @var{filename} argument is stored in the newly created
154 BFD. It can be accessed via the bfd_get_filename() macro.
157 @subsubsection @code{bfd_openw}
160 bfd *bfd_openw (const char *filename, const char *target);
162 @strong{Description}@*
163 Create a BFD, associated with file @var{filename}, using the
164 file format @var{target}, and return a pointer to it.
166 Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory},
167 @code{bfd_error_invalid_target}.
169 A copy of the @var{filename} argument is stored in the newly created
170 BFD. It can be accessed via the bfd_get_filename() macro.
173 @subsubsection @code{bfd_close}
176 bfd_boolean bfd_close (bfd *abfd);
178 @strong{Description}@*
179 Close a BFD. If the BFD was open for writing, then pending
180 operations are completed and the file written out and closed.
181 If the created file is executable, then @code{chmod} is called
184 All memory attached to the BFD is released.
186 The file descriptor associated with the BFD is closed (even
187 if it was passed in to BFD by @code{bfd_fdopenr}).
190 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
192 @findex bfd_close_all_done
193 @subsubsection @code{bfd_close_all_done}
196 bfd_boolean bfd_close_all_done (bfd *);
198 @strong{Description}@*
199 Close a BFD. Differs from @code{bfd_close} since it does not
200 complete any pending operations. This routine would be used
201 if the application had just used BFD for swapping and didn't
202 want to use any of the writing code.
204 If the created file is executable, then @code{chmod} is called
207 All memory attached to the BFD is released.
210 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
213 @subsubsection @code{bfd_create}
216 bfd *bfd_create (const char *filename, bfd *templ);
218 @strong{Description}@*
219 Create a new BFD in the manner of @code{bfd_openw}, but without
220 opening a file. The new BFD takes the target from the target
221 used by @var{templ}. The format is always set to @code{bfd_object}.
223 A copy of the @var{filename} argument is stored in the newly created
224 BFD. It can be accessed via the bfd_get_filename() macro.
226 @findex bfd_make_writable
227 @subsubsection @code{bfd_make_writable}
230 bfd_boolean bfd_make_writable (bfd *abfd);
232 @strong{Description}@*
233 Takes a BFD as created by @code{bfd_create} and converts it
234 into one like as returned by @code{bfd_openw}. It does this
235 by converting the BFD to BFD_IN_MEMORY. It's assumed that
236 you will call @code{bfd_make_readable} on this bfd later.
239 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
241 @findex bfd_make_readable
242 @subsubsection @code{bfd_make_readable}
245 bfd_boolean bfd_make_readable (bfd *abfd);
247 @strong{Description}@*
248 Takes a BFD as created by @code{bfd_create} and
249 @code{bfd_make_writable} and converts it into one like as
250 returned by @code{bfd_openr}. It does this by writing the
251 contents out to the memory buffer, then reversing the
255 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
258 @subsubsection @code{bfd_alloc}
261 void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
263 @strong{Description}@*
264 Allocate a block of @var{wanted} bytes of memory attached to
265 @code{abfd} and return a pointer to it.
268 @subsubsection @code{bfd_alloc2}
271 void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
273 @strong{Description}@*
274 Allocate a block of @var{nmemb} elements of @var{size} bytes each
275 of memory attached to @code{abfd} and return a pointer to it.
278 @subsubsection @code{bfd_zalloc}
281 void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
283 @strong{Description}@*
284 Allocate a block of @var{wanted} bytes of zeroed memory
285 attached to @code{abfd} and return a pointer to it.
288 @subsubsection @code{bfd_zalloc2}
291 void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
293 @strong{Description}@*
294 Allocate a block of @var{nmemb} elements of @var{size} bytes each
295 of zeroed memory attached to @code{abfd} and return a pointer to it.
297 @findex bfd_calc_gnu_debuglink_crc32
298 @subsubsection @code{bfd_calc_gnu_debuglink_crc32}
301 unsigned long bfd_calc_gnu_debuglink_crc32
302 (unsigned long crc, const unsigned char *buf, bfd_size_type len);
304 @strong{Description}@*
305 Computes a CRC value as used in the .gnu_debuglink section.
306 Advances the previously computed @var{crc} value by computing
307 and adding in the crc32 for @var{len} bytes of @var{buf}.
310 Return the updated CRC32 value.
312 @findex bfd_get_debug_link_info
313 @subsubsection @code{bfd_get_debug_link_info}
316 char *bfd_get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
318 @strong{Description}@*
319 Fetch the filename and CRC32 value for any separate debuginfo
320 associated with @var{abfd}. Return NULL if no such info found,
321 otherwise return filename and update @var{crc32_out}. The
322 returned filename is allocated with @code{malloc}; freeing it
323 is the responsibility of the caller.
325 @findex bfd_get_alt_debug_link_info
326 @subsubsection @code{bfd_get_alt_debug_link_info}
329 char *bfd_get_alt_debug_link_info (bfd * abfd,
330 bfd_size_type *buildid_len,
331 bfd_byte **buildid_out);
333 @strong{Description}@*
334 Fetch the filename and BuildID value for any alternate debuginfo
335 associated with @var{abfd}. Return NULL if no such info found,
336 otherwise return filename and update @var{buildid_len} and
337 @var{buildid_out}. The returned filename and build_id are
338 allocated with @code{malloc}; freeing them is the
339 responsibility of the caller.
341 @findex separate_debug_file_exists
342 @subsubsection @code{separate_debug_file_exists}
345 bfd_boolean separate_debug_file_exists
346 (char *name, unsigned long crc32);
348 @strong{Description}@*
349 Checks to see if @var{name} is a file and if its contents
352 @findex separate_alt_debug_file_exists
353 @subsubsection @code{separate_alt_debug_file_exists}
356 bfd_boolean separate_alt_debug_file_exists
357 (char *name, unsigned long crc32);
359 @strong{Description}@*
360 Checks to see if @var{name} is a file and if its BuildID
361 matches @var{buildid}.
363 @findex find_separate_debug_file
364 @subsubsection @code{find_separate_debug_file}
367 char *find_separate_debug_file (bfd *abfd);
369 @strong{Description}@*
370 Searches @var{abfd} for a section called @var{section_name} which
371 is expected to contain a reference to a file containing separate
372 debugging information. The function scans various locations in
373 the filesystem, including the file tree rooted at
374 @var{debug_file_directory}, and returns the first matching
375 filename that it finds. If @var{check_crc} is TRUE then the
376 contents of the file must also match the CRC value contained in
377 @var{section_name}. Returns NULL if no valid file could be found.
379 @findex bfd_follow_gnu_debuglink
380 @subsubsection @code{bfd_follow_gnu_debuglink}
383 char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
385 @strong{Description}@*
386 Takes a BFD and searches it for a .gnu_debuglink section. If this
387 section is found, it examines the section for the name and checksum
388 of a '.debug' file containing auxiliary debugging information. It
389 then searches the filesystem for this .debug file in some standard
390 locations, including the directory tree rooted at @var{dir}, and if
391 found returns the full filename.
393 If @var{dir} is NULL, it will search a default path configured into
394 libbfd at build time. [XXX this feature is not currently
398 @code{NULL} on any errors or failure to locate the .debug file,
399 otherwise a pointer to a heap-allocated string containing the
400 filename. The caller is responsible for freeing this string.
402 @findex bfd_follow_gnu_debugaltlink
403 @subsubsection @code{bfd_follow_gnu_debugaltlink}
406 char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir);
408 @strong{Description}@*
409 Takes a BFD and searches it for a .gnu_debugaltlink section. If this
410 section is found, it examines the section for the name of a file
411 containing auxiliary debugging information. It then searches the
412 filesystem for this file in a set of standard locations, including
413 the directory tree rooted at @var{dir}, and if found returns the
416 If @var{dir} is NULL, it will search a default path configured into
417 libbfd at build time. [FIXME: This feature is not currently
421 @code{NULL} on any errors or failure to locate the debug file,
422 otherwise a pointer to a heap-allocated string containing the
423 filename. The caller is responsible for freeing this string.
425 @findex bfd_create_gnu_debuglink_section
426 @subsubsection @code{bfd_create_gnu_debuglink_section}
429 struct bfd_section *bfd_create_gnu_debuglink_section
430 (bfd *abfd, const char *filename);
432 @strong{Description}@*
433 Takes a @var{BFD} and adds a .gnu_debuglink section to it. The section is sized
434 to be big enough to contain a link to the specified @var{filename}.
437 A pointer to the new section is returned if all is ok. Otherwise @code{NULL} is
438 returned and bfd_error is set.
440 @findex bfd_fill_in_gnu_debuglink_section
441 @subsubsection @code{bfd_fill_in_gnu_debuglink_section}
444 bfd_boolean bfd_fill_in_gnu_debuglink_section
445 (bfd *abfd, struct bfd_section *sect, const char *filename);
447 @strong{Description}@*
448 Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
449 and fills in the contents of the section to contain a link to the
450 specified @var{filename}. The filename should be relative to the
454 @code{TRUE} is returned if all is ok. Otherwise @code{FALSE} is returned
455 and bfd_error is set.