OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-old/] [binutils-2.18.50/] [bfd/] [doc/] [opncls.texi] - Blame information for rev 816

Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.