1 |
205 |
julius |
@findex struct bfd_iovec
|
2 |
|
|
@subsubsection @code{struct bfd_iovec}
|
3 |
|
|
@strong{Description}@*
|
4 |
|
|
The @code{struct bfd_iovec} contains the internal file I/O class.
|
5 |
|
|
Each @code{BFD} has an instance of this class and all file I/O is
|
6 |
|
|
routed through it (it is assumed that the instance implements
|
7 |
|
|
all methods listed below).
|
8 |
|
|
@example
|
9 |
|
|
struct bfd_iovec
|
10 |
|
|
@{
|
11 |
|
|
/* To avoid problems with macros, a "b" rather than "f"
|
12 |
|
|
prefix is prepended to each method name. */
|
13 |
|
|
/* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching
|
14 |
|
|
bytes starting at PTR. Return the number of bytes actually
|
15 |
|
|
transfered (a read past end-of-file returns less than NBYTES),
|
16 |
|
|
or -1 (setting @code{bfd_error}) if an error occurs. */
|
17 |
|
|
file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes);
|
18 |
|
|
file_ptr (*bwrite) (struct bfd *abfd, const void *ptr,
|
19 |
|
|
file_ptr nbytes);
|
20 |
|
|
/* Return the current IOSTREAM file offset, or -1 (setting @code{bfd_error}
|
21 |
|
|
if an error occurs. */
|
22 |
|
|
file_ptr (*btell) (struct bfd *abfd);
|
23 |
|
|
/* For the following, on successful completion a value of 0 is returned.
|
24 |
|
|
Otherwise, a value of -1 is returned (and @code{bfd_error} is set). */
|
25 |
|
|
int (*bseek) (struct bfd *abfd, file_ptr offset, int whence);
|
26 |
|
|
int (*bclose) (struct bfd *abfd);
|
27 |
|
|
int (*bflush) (struct bfd *abfd);
|
28 |
|
|
int (*bstat) (struct bfd *abfd, struct stat *sb);
|
29 |
|
|
/* Just like mmap: (void*)-1 on failure, mmapped address on success. */
|
30 |
|
|
void *(*bmmap) (struct bfd *abfd, void *addr, bfd_size_type len,
|
31 |
|
|
int prot, int flags, file_ptr offset);
|
32 |
|
|
@};
|
33 |
|
|
@end example
|
34 |
|
|
|
35 |
|
|
@findex bfd_get_mtime
|
36 |
|
|
@subsubsection @code{bfd_get_mtime}
|
37 |
|
|
@strong{Synopsis}
|
38 |
|
|
@example
|
39 |
|
|
long bfd_get_mtime (bfd *abfd);
|
40 |
|
|
@end example
|
41 |
|
|
@strong{Description}@*
|
42 |
|
|
Return the file modification time (as read from the file system, or
|
43 |
|
|
from the archive header for archive members).
|
44 |
|
|
|
45 |
|
|
@findex bfd_get_size
|
46 |
|
|
@subsubsection @code{bfd_get_size}
|
47 |
|
|
@strong{Synopsis}
|
48 |
|
|
@example
|
49 |
|
|
file_ptr bfd_get_size (bfd *abfd);
|
50 |
|
|
@end example
|
51 |
|
|
@strong{Description}@*
|
52 |
|
|
Return the file size (as read from file system) for the file
|
53 |
|
|
associated with BFD @var{abfd}.
|
54 |
|
|
|
55 |
|
|
The initial motivation for, and use of, this routine is not
|
56 |
|
|
so we can get the exact size of the object the BFD applies to, since
|
57 |
|
|
that might not be generally possible (archive members for example).
|
58 |
|
|
It would be ideal if someone could eventually modify
|
59 |
|
|
it so that such results were guaranteed.
|
60 |
|
|
|
61 |
|
|
Instead, we want to ask questions like "is this NNN byte sized
|
62 |
|
|
object I'm about to try read from file offset YYY reasonable?"
|
63 |
|
|
As as example of where we might do this, some object formats
|
64 |
|
|
use string tables for which the first @code{sizeof (long)} bytes of the
|
65 |
|
|
table contain the size of the table itself, including the size bytes.
|
66 |
|
|
If an application tries to read what it thinks is one of these
|
67 |
|
|
string tables, without some way to validate the size, and for
|
68 |
|
|
some reason the size is wrong (byte swapping error, wrong location
|
69 |
|
|
for the string table, etc.), the only clue is likely to be a read
|
70 |
|
|
error when it tries to read the table, or a "virtual memory
|
71 |
|
|
exhausted" error when it tries to allocate 15 bazillon bytes
|
72 |
|
|
of space for the 15 bazillon byte table it is about to read.
|
73 |
|
|
This function at least allows us to answer the question, "is the
|
74 |
|
|
size reasonable?".
|
75 |
|
|
|
76 |
|
|
@findex bfd_mmap
|
77 |
|
|
@subsubsection @code{bfd_mmap}
|
78 |
|
|
@strong{Synopsis}
|
79 |
|
|
@example
|
80 |
|
|
void *bfd_mmap (bfd *abfd, void *addr, bfd_size_type len,
|
81 |
|
|
int prot, int flags, file_ptr offset);
|
82 |
|
|
@end example
|
83 |
|
|
@strong{Description}@*
|
84 |
|
|
Return mmap()ed region of the file, if possible and implemented.
|
85 |
|
|
|