Home | History | Annotate | Line # | Download | only in doc 
      1 @section File caching
      2 The file caching mechanism is embedded within BFD and allows
      3 the application to open as many BFDs as it wants without
      4 regard to the underlying operating system's file descriptor
      5 limit (often as low as 20 open files).  The module in
      6 @code{cache.c} maintains a least recently used list of
      7 @code{bfd_cache_max_open} files, and exports the name
      8 @code{bfd_cache_lookup}, which runs around and makes sure that
      9 the required BFD is open. If not, then it chooses a file to
     10 close, closes it and opens the one wanted, returning its file
     11 handle.
     12 
     13 @subsection Caching functions
     14 
     15 
     16 @findex bfd_cache_init
     17 @subsubsection @code{bfd_cache_init}
     18 @deftypefn {Function} bool bfd_cache_init (bfd *abfd); 
     19 Add a newly opened BFD to the cache.
     20 
     21 @end deftypefn
     22 @findex bfd_cache_close
     23 @subsubsection @code{bfd_cache_close}
     24 @deftypefn {Function} bool bfd_cache_close (bfd *abfd); 
     25 Remove the BFD @var{abfd} from the cache. If the attached file is open,
     26 then close it too.
     27 
     28 @code{FALSE} is returned if closing the file fails, @code{TRUE} is
     29 returned if all is well.
     30 
     31 @end deftypefn
     32 @findex bfd_cache_close_all
     33 @subsubsection @code{bfd_cache_close_all}
     34 @deftypefn {Function} bool bfd_cache_close_all (void); 
     35 Remove all BFDs from the cache. If the attached file is open,
     36 then close it too.  Note - despite its name this function will
     37 close a BFD even if it is not marked as being cacheable, ie
     38 even if bfd_get_cacheable() returns false.
     39 
     40 @code{FALSE} is returned if closing one of the file fails, @code{TRUE} is
     41 returned if all is well.
     42 
     43 @end deftypefn
     44 @findex bfd_cache_set_uncloseable
     45 @subsubsection @code{bfd_cache_set_uncloseable}
     46 @deftypefn {Function} bool bfd_cache_set_uncloseable (bfd *abfd, bool value, bool *old); 
     47 Internal function to mark ABFD as either closeable or not.
     48 This is used by bfd_check_format_matches to avoid races
     49 where bfd_cache_close_all is called in another thread.
     50 VALUE is true to mark the BFD as temporarily uncloseable
     51 by the cache; false to mark it as closeable once again.
     52 OLD, if non-NULL, is set to the previous value of the flag.
     53 Returns false on error, true on success.
     54 
     55 @end deftypefn
     56 @findex bfd_cache_size
     57 @subsubsection @code{bfd_cache_size}
     58 @deftypefn {Function} unsigned bfd_cache_size (void); 
     59 Return the number of open files in the cache.
     60 
     61 @end deftypefn
     62 @findex bfd_open_file
     63 @subsubsection @code{bfd_open_file}
     64 @deftypefn {Function} FILE* bfd_open_file (bfd *abfd); 
     65 Call the OS to open a file for @var{abfd}.  Return the @code{FILE *}
     66 (possibly @code{NULL}) that results from this operation.  Set up the
     67 BFD so that future accesses know the file is open. If the @code{FILE *}
     68 returned is @code{NULL}, then it won't have been put in the
     69 cache, so it won't have to be removed from it.
     70 
     71 @end deftypefn
     72