diff options
Diffstat (limited to 'bfd/doc/bfdio.texi')
| -rw-r--r-- | bfd/doc/bfdio.texi | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/bfd/doc/bfdio.texi b/bfd/doc/bfdio.texi new file mode 100644 index 0000000000..ff8275fcb0 --- /dev/null +++ b/bfd/doc/bfdio.texi @@ -0,0 +1,95 @@ +@findex struct bfd_iovec +@subsubsection @code{struct bfd_iovec} +@strong{Description}@* +The @code{struct bfd_iovec} contains the internal file I/O class. +Each @code{BFD} has an instance of this class and all file I/O is +routed through it (it is assumed that the instance implements +all methods listed below). +@example +struct bfd_iovec +@{ + /* To avoid problems with macros, a "b" rather than "f" + prefix is prepended to each method name. */ + /* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching + bytes starting at PTR. Return the number of bytes actually + transfered (a read past end-of-file returns less than NBYTES), + or -1 (setting @code{bfd_error}) if an error occurs. */ + file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes); + file_ptr (*bwrite) (struct bfd *abfd, const void *ptr, + file_ptr nbytes); + /* Return the current IOSTREAM file offset, or -1 (setting @code{bfd_error} + if an error occurs. */ + file_ptr (*btell) (struct bfd *abfd); + /* For the following, on successful completion a value of 0 is returned. + Otherwise, a value of -1 is returned (and @code{bfd_error} is set). */ + int (*bseek) (struct bfd *abfd, file_ptr offset, int whence); + int (*bclose) (struct bfd *abfd); + int (*bflush) (struct bfd *abfd); + int (*bstat) (struct bfd *abfd, struct stat *sb); + /* Mmap a part of the files. ADDR, LEN, PROT, FLAGS and OFFSET are the usual + mmap parameter, except that LEN and OFFSET do not need to be page + aligned. Returns (void *)-1 on failure, mmapped address on success. + Also write in MAP_ADDR the address of the page aligned buffer and in + MAP_LEN the size mapped (a page multiple). Use unmap with MAP_ADDR and + MAP_LEN to unmap. */ + void *(*bmmap) (struct bfd *abfd, void *addr, bfd_size_type len, + int prot, int flags, file_ptr offset, + void **map_addr, bfd_size_type *map_len); +@}; +extern const struct bfd_iovec _bfd_memory_iovec; +@end example + +@findex bfd_get_mtime +@subsubsection @code{bfd_get_mtime} +@strong{Synopsis} +@example +long bfd_get_mtime (bfd *abfd); +@end example +@strong{Description}@* +Return the file modification time (as read from the file system, or +from the archive header for archive members). + +@findex bfd_get_size +@subsubsection @code{bfd_get_size} +@strong{Synopsis} +@example +file_ptr bfd_get_size (bfd *abfd); +@end example +@strong{Description}@* +Return the file size (as read from file system) for the file +associated with BFD @var{abfd}. + +The initial motivation for, and use of, this routine is not +so we can get the exact size of the object the BFD applies to, since +that might not be generally possible (archive members for example). +It would be ideal if someone could eventually modify +it so that such results were guaranteed. + +Instead, we want to ask questions like "is this NNN byte sized +object I'm about to try read from file offset YYY reasonable?" +As as example of where we might do this, some object formats +use string tables for which the first @code{sizeof (long)} bytes of the +table contain the size of the table itself, including the size bytes. +If an application tries to read what it thinks is one of these +string tables, without some way to validate the size, and for +some reason the size is wrong (byte swapping error, wrong location +for the string table, etc.), the only clue is likely to be a read +error when it tries to read the table, or a "virtual memory +exhausted" error when it tries to allocate 15 bazillon bytes +of space for the 15 bazillon byte table it is about to read. +This function at least allows us to answer the question, "is the +size reasonable?". + +@findex bfd_mmap +@subsubsection @code{bfd_mmap} +@strong{Synopsis} +@example +void *bfd_mmap (bfd *abfd, void *addr, bfd_size_type len, + int prot, int flags, file_ptr offset, + void **map_addr, bfd_size_type *map_len); +@end example +@strong{Description}@* +Return mmap()ed region of the file, if possible and implemented. +LEN and OFFSET do not need to be page aligned. The page aligned +address and length are written to MAP_ADDR and MAP_LEN. + |