File: opncls.texi

package info (click to toggle)
binutils-h8300-hms 2.16.1-10
  • links: PTS
  • area: main
  • in suites: bookworm, bullseye, buster, jessie, jessie-kfreebsd, sid, stretch, trixie
  • size: 98,956 kB
  • sloc: ansic: 702,356; asm: 261,813; exp: 45,962; makefile: 39,435; sh: 16,735; lisp: 8,454; yacc: 5,941; lex: 1,541; perl: 1,382; cpp: 1,339; sed: 285; pascal: 175; awk: 26
file content (319 lines) | stat: -rw-r--r-- 10,758 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
@subsection Opening and closing BFDs


@findex bfd_openr
@subsubsection @code{bfd_openr}
@strong{Synopsis}
@example
bfd *bfd_openr (const char *filename, const char *target);
@end example
@strong{Description}@*
Open the file @var{filename} (using @code{fopen}) with the target
@var{target}.  Return a pointer to the created BFD.

Calls @code{bfd_find_target}, so @var{target} is interpreted as by
that function.

If @code{NULL} is returned then an error has occured.   Possible errors
are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
@code{system_call} error.

@findex bfd_fdopenr
@subsubsection @code{bfd_fdopenr}
@strong{Synopsis}
@example
bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
@end example
@strong{Description}@*
@code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to
@code{fopen}.  It opens a BFD on a file already described by the
@var{fd} supplied.

When the file is later @code{bfd_close}d, the file descriptor will
be closed.  If the caller desires that this file descriptor be
cached by BFD (opened as needed, closed as needed to free
descriptors for other opens), with the supplied @var{fd} used as
an initial file descriptor (but subject to closure at any time),
call bfd_set_cacheable(bfd, 1) on the returned BFD.  The default
is to assume no caching; the file descriptor will remain open
until @code{bfd_close}, and will not be affected by BFD operations
on other files.

Possible errors are @code{bfd_error_no_memory},
@code{bfd_error_invalid_target} and @code{bfd_error_system_call}.

@findex bfd_openstreamr
@subsubsection @code{bfd_openstreamr}
@strong{Synopsis}
@example
bfd *bfd_openstreamr (const char *, const char *, void *);
@end example
@strong{Description}@*
Open a BFD for read access on an existing stdio stream.  When
the BFD is passed to @code{bfd_close}, the stream will be closed.

@findex bfd_openr_iovec
@subsubsection @code{bfd_openr_iovec}
@strong{Synopsis}
@example
bfd *bfd_openr_iovec (const char *filename, const char *target,
    void *(*open) (struct bfd *nbfd,
    void *open_closure),
    void *open_closure,
    file_ptr (*pread) (struct bfd *nbfd,
    void *stream,
    void *buf,
    file_ptr nbytes,
    file_ptr offset),
    int (*close) (struct bfd *nbfd,
    void *stream));
@end example
@strong{Description}@*
Create and return a BFD backed by a read-only @var{stream}.
The @var{stream} is created using @var{open}, accessed using
@var{pread} and destroyed using @var{close}.

Calls @code{bfd_find_target}, so @var{target} is interpreted as by
that function.

Calls @var{open} (which can call @code{bfd_zalloc} and
@code{bfd_get_filename}) to obtain the read-only stream backing
the BFD.  @var{open} either succeeds returning the
non-@code{NULL} @var{stream}, or fails returning @code{NULL}
(setting @code{bfd_error}).

Calls @var{pread} to request @var{nbytes} of data from
@var{stream} starting at @var{offset} (e.g., via a call to
@code{bfd_read}).  @var{pread} either succeeds returning the
number of bytes read (which can be less than @var{nbytes} when
end-of-file), or fails returning -1 (setting @code{bfd_error}).

Calls @var{close} when the BFD is later closed using
@code{bfd_close}.  @var{close} either succeeds returning 0, or
fails returning -1 (setting @code{bfd_error}).

If @code{bfd_openr_iovec} returns @code{NULL} then an error has
occurred.  Possible errors are @code{bfd_error_no_memory},
@code{bfd_error_invalid_target} and @code{bfd_error_system_call}.

@findex bfd_openw
@subsubsection @code{bfd_openw}
@strong{Synopsis}
@example
bfd *bfd_openw (const char *filename, const char *target);
@end example
@strong{Description}@*
Create a BFD, associated with file @var{filename}, using the
file format @var{target}, and return a pointer to it.

Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory},
@code{bfd_error_invalid_target}.

@findex bfd_close
@subsubsection @code{bfd_close}
@strong{Synopsis}
@example
bfd_boolean bfd_close (bfd *abfd);
@end example
@strong{Description}@*
Close a BFD. If the BFD was open for writing, then pending
operations are completed and the file written out and closed.
If the created file is executable, then @code{chmod} is called
to mark it as such.

All memory attached to the BFD is released.

The file descriptor associated with the BFD is closed (even
if it was passed in to BFD by @code{bfd_fdopenr}).

@strong{Returns}@*
@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.

@findex bfd_close_all_done
@subsubsection @code{bfd_close_all_done}
@strong{Synopsis}
@example
bfd_boolean bfd_close_all_done (bfd *);
@end example
@strong{Description}@*
Close a BFD.  Differs from @code{bfd_close} since it does not
complete any pending operations.  This routine would be used
if the application had just used BFD for swapping and didn't
want to use any of the writing code.

If the created file is executable, then @code{chmod} is called
to mark it as such.

All memory attached to the BFD is released.

@strong{Returns}@*
@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.

@findex bfd_create
@subsubsection @code{bfd_create}
@strong{Synopsis}
@example
bfd *bfd_create (const char *filename, bfd *templ);
@end example
@strong{Description}@*
Create a new BFD in the manner of @code{bfd_openw}, but without
opening a file. The new BFD takes the target from the target
used by @var{template}. The format is always set to @code{bfd_object}.

@findex bfd_make_writable
@subsubsection @code{bfd_make_writable}
@strong{Synopsis}
@example
bfd_boolean bfd_make_writable (bfd *abfd);
@end example
@strong{Description}@*
Takes a BFD as created by @code{bfd_create} and converts it
into one like as returned by @code{bfd_openw}.  It does this
by converting the BFD to BFD_IN_MEMORY.  It's assumed that
you will call @code{bfd_make_readable} on this bfd later.

@strong{Returns}@*
@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.

@findex bfd_make_readable
@subsubsection @code{bfd_make_readable}
@strong{Synopsis}
@example
bfd_boolean bfd_make_readable (bfd *abfd);
@end example
@strong{Description}@*
Takes a BFD as created by @code{bfd_create} and
@code{bfd_make_writable} and converts it into one like as
returned by @code{bfd_openr}.  It does this by writing the
contents out to the memory buffer, then reversing the
direction.

@strong{Returns}@*
@code{TRUE} is returned if all is ok, otherwise @code{FALSE}.

@findex bfd_alloc
@subsubsection @code{bfd_alloc}
@strong{Synopsis}
@example
void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
@end example
@strong{Description}@*
Allocate a block of @var{wanted} bytes of memory attached to
@code{abfd} and return a pointer to it.

@findex bfd_zalloc
@subsubsection @code{bfd_zalloc}
@strong{Synopsis}
@example
void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
@end example
@strong{Description}@*
Allocate a block of @var{wanted} bytes of zeroed memory
attached to @code{abfd} and return a pointer to it.

@findex bfd_calc_gnu_debuglink_crc32
@subsubsection @code{bfd_calc_gnu_debuglink_crc32}
@strong{Synopsis}
@example
unsigned long bfd_calc_gnu_debuglink_crc32
   (unsigned long crc, const unsigned char *buf, bfd_size_type len);
@end example
@strong{Description}@*
Computes a CRC value as used in the .gnu_debuglink section.
Advances the previously computed @var{crc} value by computing
and adding in the crc32 for @var{len} bytes of @var{buf}.

@strong{Returns}@*
Return the updated CRC32 value.

@findex get_debug_link_info
@subsubsection @code{get_debug_link_info}
@strong{Synopsis}
@example
char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
@end example
@strong{Description}@*
fetch the filename and CRC32 value for any separate debuginfo
associated with @var{abfd}. Return NULL if no such info found,
otherwise return filename and update @var{crc32_out}.

@findex separate_debug_file_exists
@subsubsection @code{separate_debug_file_exists}
@strong{Synopsis}
@example
bfd_boolean separate_debug_file_exists
   (char *name, unsigned long crc32);
@end example
@strong{Description}@*
Checks to see if @var{name} is a file and if its contents
match @var{crc32}.

@findex find_separate_debug_file
@subsubsection @code{find_separate_debug_file}
@strong{Synopsis}
@example
char *find_separate_debug_file (bfd *abfd);
@end example
@strong{Description}@*
Searches @var{abfd} for a reference to separate debugging
information, scans various locations in the filesystem, including
the file tree rooted at @var{debug_file_directory}, and returns a
filename of such debugging information if the file is found and has
matching CRC32.  Returns NULL if no reference to debugging file
exists, or file cannot be found.

@findex bfd_follow_gnu_debuglink
@subsubsection @code{bfd_follow_gnu_debuglink}
@strong{Synopsis}
@example
char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
@end example
@strong{Description}@*
Takes a BFD and searches it for a .gnu_debuglink section.  If this
section is found, it examines the section for the name and checksum
of a '.debug' file containing auxiliary debugging information.  It
then searches the filesystem for this .debug file in some standard
locations, including the directory tree rooted at @var{dir}, and if
found returns the full filename.

If @var{dir} is NULL, it will search a default path configured into
libbfd at build time.  [XXX this feature is not currently
implemented].

@strong{Returns}@*
@code{NULL} on any errors or failure to locate the .debug file,
otherwise a pointer to a heap-allocated string containing the
filename.  The caller is responsible for freeing this string.

@findex bfd_create_gnu_debuglink_section
@subsubsection @code{bfd_create_gnu_debuglink_section}
@strong{Synopsis}
@example
struct bfd_section *bfd_create_gnu_debuglink_section
   (bfd *abfd, const char *filename);
@end example
@strong{Description}@*
Takes a @var{BFD} and adds a .gnu_debuglink section to it.  The section is sized
to be big enough to contain a link to the specified @var{filename}.

@strong{Returns}@*
A pointer to the new section is returned if all is ok.  Otherwise @code{NULL} is
returned and bfd_error is set.

@findex bfd_fill_in_gnu_debuglink_section
@subsubsection @code{bfd_fill_in_gnu_debuglink_section}
@strong{Synopsis}
@example
bfd_boolean bfd_fill_in_gnu_debuglink_section
   (bfd *abfd, struct bfd_section *sect, const char *filename);
@end example
@strong{Description}@*
Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
and fills in the contents of the section to contain a link to the
specified @var{filename}.  The filename should be relative to the
current directory.

@strong{Returns}@*
@code{TRUE} is returned if all is ok.  Otherwise @code{FALSE} is returned
and bfd_error is set.