1 @section Opening and closing BFDs
5 @subsubsection @code{bfd_openr}
8 bfd *bfd_openr (const char *filename, const char *target);
10 @strong{Description}@*
11 Open the file @var{filename} (using @code{fopen}) with the target
12 @var{target}. Return a pointer to the created BFD.
14 Calls @code{bfd_find_target}, so @var{target} is interpreted as by
17 If @code{NULL} is returned then an error has occured. Possible errors
18 are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
19 @code{system_call} error.
22 @subsubsection @code{bfd_fdopenr}
25 bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
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
32 When the file is later @code{bfd_close}d, the file descriptor will
33 be closed. If the caller desires that this file descriptor be
34 cached by BFD (opened as needed, closed as needed to free
35 descriptors for other opens), with the supplied @var{fd} used as
36 an initial file descriptor (but subject to closure at any time),
37 call bfd_set_cacheable(bfd, 1) on the returned BFD. The default
38 is to assume no caching; the file descriptor will remain open
39 until @code{bfd_close}, and will not be affected by BFD operations
42 Possible errors are @code{bfd_error_no_memory},
43 @code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
45 @findex bfd_openstreamr
46 @subsubsection @code{bfd_openstreamr}
49 bfd *bfd_openstreamr (const char *, const char *, void *);
51 @strong{Description}@*
52 Open a BFD for read access on an existing stdio stream. When
53 the BFD is passed to @code{bfd_close}, the stream will be closed.
56 @subsubsection @code{bfd_openw}
59 bfd *bfd_openw (const char *filename, const char *target);
61 @strong{Description}@*
62 Create a BFD, associated with file @var{filename}, using the
63 file format @var{target}, and return a pointer to it.
65 Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory},
66 @code{bfd_error_invalid_target}.
69 @subsubsection @code{bfd_close}
72 bfd_boolean bfd_close (bfd *abfd);
74 @strong{Description}@*
75 Close a BFD. If the BFD was open for writing, then pending
76 operations are completed and the file written out and closed.
77 If the created file is executable, then @code{chmod} is called
80 All memory attached to the BFD is released.
82 The file descriptor associated with the BFD is closed (even
83 if it was passed in to BFD by @code{bfd_fdopenr}).
86 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
88 @findex bfd_close_all_done
89 @subsubsection @code{bfd_close_all_done}
92 bfd_boolean bfd_close_all_done (bfd *);
94 @strong{Description}@*
95 Close a BFD. Differs from @code{bfd_close} since it does not
96 complete any pending operations. This routine would be used
97 if the application had just used BFD for swapping and didn't
98 want to use any of the writing code.
100 If the created file is executable, then @code{chmod} is called
103 All memory attached to the BFD is released.
106 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
109 @subsubsection @code{bfd_create}
112 bfd *bfd_create (const char *filename, bfd *templ);
114 @strong{Description}@*
115 Create a new BFD in the manner of @code{bfd_openw}, but without
116 opening a file. The new BFD takes the target from the target
117 used by @var{template}. The format is always set to @code{bfd_object}.
119 @findex bfd_make_writable
120 @subsubsection @code{bfd_make_writable}
123 bfd_boolean bfd_make_writable (bfd *abfd);
125 @strong{Description}@*
126 Takes a BFD as created by @code{bfd_create} and converts it
127 into one like as returned by @code{bfd_openw}. It does this
128 by converting the BFD to BFD_IN_MEMORY. It's assumed that
129 you will call @code{bfd_make_readable} on this bfd later.
132 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
134 @findex bfd_make_readable
135 @subsubsection @code{bfd_make_readable}
138 bfd_boolean bfd_make_readable (bfd *abfd);
140 @strong{Description}@*
141 Takes a BFD as created by @code{bfd_create} and
142 @code{bfd_make_writable} and converts it into one like as
143 returned by @code{bfd_openr}. It does this by writing the
144 contents out to the memory buffer, then reversing the
148 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
151 @subsubsection @code{bfd_alloc}
154 void *bfd_alloc (bfd *abfd, size_t wanted);
156 @strong{Description}@*
157 Allocate a block of @var{wanted} bytes of memory attached to
158 @code{abfd} and return a pointer to it.
160 @findex bfd_calc_gnu_debuglink_crc32
161 @subsubsection @code{bfd_calc_gnu_debuglink_crc32}
164 unsigned long bfd_calc_gnu_debuglink_crc32
165 (unsigned long crc, const unsigned char *buf, bfd_size_type len);
167 @strong{Description}@*
168 Computes a CRC value as used in the .gnu_debuglink section.
169 Advances the previously computed @var{crc} value by computing
170 and adding in the crc32 for @var{len} bytes of @var{buf}.
173 Return the updated CRC32 value.
175 @findex get_debug_link_info
176 @subsubsection @code{get_debug_link_info}
179 char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
181 @strong{Description}@*
182 fetch the filename and CRC32 value for any separate debuginfo
183 associated with @var{abfd}. Return NULL if no such info found,
184 otherwise return filename and update @var{crc32_out}.
186 @findex separate_debug_file_exists
187 @subsubsection @code{separate_debug_file_exists}
190 bfd_boolean separate_debug_file_exists
191 (char *name, unsigned long crc32);
193 @strong{Description}@*
194 Checks to see if @var{name} is a file and if its contents
197 @findex find_separate_debug_file
198 @subsubsection @code{find_separate_debug_file}
201 char *find_separate_debug_file (bfd *abfd);
203 @strong{Description}@*
204 Searches @var{abfd} for a reference to separate debugging
205 information, scans various locations in the filesystem, including
206 the file tree rooted at @var{debug_file_directory}, and returns a
207 filename of such debugging information if the file is found and has
208 matching CRC32. Returns NULL if no reference to debugging file
209 exists, or file cannot be found.
211 @findex bfd_follow_gnu_debuglink
212 @subsubsection @code{bfd_follow_gnu_debuglink}
215 char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
217 @strong{Description}@*
218 Takes a BFD and searches it for a .gnu_debuglink section. If this
219 section is found, it examines the section for the name and checksum
220 of a '.debug' file containing auxiliary debugging information. It
221 then searches the filesystem for this .debug file in some standard
222 locations, including the directory tree rooted at @var{dir}, and if
223 found returns the full filename.
225 If @var{dir} is NULL, it will search a default path configured into
226 libbfd at build time. [XXX this feature is not currently
230 @code{NULL} on any errors or failure to locate the .debug file,
231 otherwise a pointer to a heap-allocated string containing the
232 filename. The caller is responsible for freeing this string.
234 @findex bfd_create_gnu_debuglink_section
235 @subsubsection @code{bfd_create_gnu_debuglink_section}
238 struct bfd_section *bfd_create_gnu_debuglink_section
239 (bfd *abfd, const char *filename);
241 @strong{Description}@*
242 Takes a @var{BFD} and adds a .gnu_debuglink section to it. The section is sized
243 to be big enough to contain a link to the specified @var{filename}.
246 A pointer to the new section is returned if all is ok. Otherwise @code{NULL} is
247 returned and bfd_error is set.
249 @findex bfd_fill_in_gnu_debuglink_section
250 @subsubsection @code{bfd_fill_in_gnu_debuglink_section}
253 bfd_boolean bfd_fill_in_gnu_debuglink_section
254 (bfd *abfd, struct bfd_section *sect, const char *filename);
256 @strong{Description}@*
257 Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
258 and fills in the contents of the section to contain a link to the
259 specified @var{filename}. The filename should be relative to the
263 @code{TRUE} is returned if all is ok. Otherwise @code{FALSE} is returned
264 and bfd_error is set.