1213239Sgonzo@findex struct bfd_iovec 2213239Sgonzo@subsubsection @code{struct bfd_iovec} 3213239Sgonzo@strong{Description}@* 4213239SgonzoThe @code{struct bfd_iovec} contains the internal file I/O class. 5213239SgonzoEach @code{BFD} has an instance of this class and all file I/O is 6213239Sgonzorouted through it (it is assumed that the instance implements 7213239Sgonzoall methods listed below). 8213239Sgonzo@example 9213239Sgonzostruct bfd_iovec 10213239Sgonzo@{ 11213239Sgonzo /* To avoid problems with macros, a "b" rather than "f" 12213239Sgonzo prefix is prepended to each method name. */ 13213239Sgonzo /* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching 14213239Sgonzo bytes starting at PTR. Return the number of bytes actually 15213239Sgonzo transfered (a read past end-of-file returns less than NBYTES), 16213239Sgonzo or -1 (setting @code{bfd_error}) if an error occurs. */ 17213239Sgonzo file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes); 18213239Sgonzo file_ptr (*bwrite) (struct bfd *abfd, const void *ptr, 19213239Sgonzo file_ptr nbytes); 20213239Sgonzo /* Return the current IOSTREAM file offset, or -1 (setting @code{bfd_error} 21213239Sgonzo if an error occurs. */ 22213239Sgonzo file_ptr (*btell) (struct bfd *abfd); 23213239Sgonzo /* For the following, on successful completion a value of 0 is returned. 24213239Sgonzo Otherwise, a value of -1 is returned (and @code{bfd_error} is set). */ 25213239Sgonzo int (*bseek) (struct bfd *abfd, file_ptr offset, int whence); 26213239Sgonzo int (*bclose) (struct bfd *abfd); 27213239Sgonzo int (*bflush) (struct bfd *abfd); 28213239Sgonzo int (*bstat) (struct bfd *abfd, struct stat *sb); 29213239Sgonzo /* Mmap a part of the files. ADDR, LEN, PROT, FLAGS and OFFSET are the usual 30213239Sgonzo mmap parameter, except that LEN and OFFSET do not need to be page 31213239Sgonzo aligned. Returns (void *)-1 on failure, mmapped address on success. 32213239Sgonzo Also write in MAP_ADDR the address of the page aligned buffer and in 33213239Sgonzo MAP_LEN the size mapped (a page multiple). Use unmap with MAP_ADDR and 34213239Sgonzo MAP_LEN to unmap. */ 35213239Sgonzo void *(*bmmap) (struct bfd *abfd, void *addr, bfd_size_type len, 36213239Sgonzo int prot, int flags, file_ptr offset, 37213239Sgonzo void **map_addr, bfd_size_type *map_len); 38213239Sgonzo@}; 39213239Sgonzoextern const struct bfd_iovec _bfd_memory_iovec; 40213239Sgonzo@end example 41213239Sgonzo 42213239Sgonzo@findex bfd_get_mtime 43213239Sgonzo@subsubsection @code{bfd_get_mtime} 44213239Sgonzo@strong{Synopsis} 45213239Sgonzo@example 46213239Sgonzolong bfd_get_mtime (bfd *abfd); 47213239Sgonzo@end example 48213239Sgonzo@strong{Description}@* 49213239SgonzoReturn the file modification time (as read from the file system, or 50213239Sgonzofrom the archive header for archive members). 51213239Sgonzo 52213239Sgonzo@findex bfd_get_size 53213239Sgonzo@subsubsection @code{bfd_get_size} 54213239Sgonzo@strong{Synopsis} 55213239Sgonzo@example 56213239Sgonzoufile_ptr bfd_get_size (bfd *abfd); 57213239Sgonzo@end example 58213239Sgonzo@strong{Description}@* 59213239SgonzoReturn the file size (as read from file system) for the file 60213239Sgonzoassociated with BFD @var{abfd}. 61213239Sgonzo 62213239SgonzoThe initial motivation for, and use of, this routine is not 63213239Sgonzoso we can get the exact size of the object the BFD applies to, since 64213239Sgonzothat might not be generally possible (archive members for example). 65213239SgonzoIt would be ideal if someone could eventually modify 66213239Sgonzoit so that such results were guaranteed. 67213239Sgonzo 68213239SgonzoInstead, we want to ask questions like "is this NNN byte sized 69213239Sgonzoobject I'm about to try read from file offset YYY reasonable?" 70213239SgonzoAs as example of where we might do this, some object formats 71213239Sgonzouse string tables for which the first @code{sizeof (long)} bytes of the 72213239Sgonzotable contain the size of the table itself, including the size bytes. 73213239SgonzoIf an application tries to read what it thinks is one of these 74213239Sgonzostring tables, without some way to validate the size, and for 75213239Sgonzosome reason the size is wrong (byte swapping error, wrong location 76213239Sgonzofor the string table, etc.), the only clue is likely to be a read 77213239Sgonzoerror when it tries to read the table, or a "virtual memory 78213239Sgonzoexhausted" error when it tries to allocate 15 bazillon bytes 79213239Sgonzoof space for the 15 bazillon byte table it is about to read. 80213239SgonzoThis function at least allows us to answer the question, "is the 81213239Sgonzosize reasonable?". 82213239Sgonzo 83213239SgonzoA return value of zero indicates the file size is unknown. 84213239Sgonzo 85213239Sgonzo@findex bfd_get_file_size 86213239Sgonzo@subsubsection @code{bfd_get_file_size} 87213239Sgonzo@strong{Synopsis} 88213239Sgonzo@example 89213239Sgonzoufile_ptr bfd_get_file_size (bfd *abfd); 90213239Sgonzo@end example 91213239Sgonzo@strong{Description}@* 92213239SgonzoReturn the file size (as read from file system) for the file 93213239Sgonzoassociated with BFD @var{abfd}. It supports both normal files 94213239Sgonzoand archive elements. 95213239Sgonzo 96213239Sgonzo@findex bfd_mmap 97213239Sgonzo@subsubsection @code{bfd_mmap} 98213239Sgonzo@strong{Synopsis} 99213239Sgonzo@example 100213239Sgonzovoid *bfd_mmap (bfd *abfd, void *addr, bfd_size_type len, 101213239Sgonzo int prot, int flags, file_ptr offset, 102213239Sgonzo void **map_addr, bfd_size_type *map_len); 103213239Sgonzo@end example 104213239Sgonzo@strong{Description}@* 105213239SgonzoReturn mmap()ed region of the file, if possible and implemented. 106213239SgonzoLEN and OFFSET do not need to be page aligned. The page aligned 107213239Sgonzoaddress and length are written to MAP_ADDR and MAP_LEN. 108213239Sgonzo 109213239Sgonzo