contrib/binutils-2.17/bfd/doc/cache.texi

   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 @strong{Synopsis}
  19 @example
  20 bfd_boolean bfd_cache_init (bfd *abfd);
  21 @end example
  22 @strong{Description}@*
  23 Add a newly opened BFD to the cache.
  24
  25 @findex bfd_cache_close
  26 @subsubsection @code{bfd_cache_close}
  27 @strong{Synopsis}
  28 @example
  29 bfd_boolean bfd_cache_close (bfd *abfd);
  30 @end example
  31 @strong{Description}@*
  32 Remove the BFD @var{abfd} from the cache. If the attached file is open,
  33 then close it too.
  34
  35 @strong{Returns}@*
  36 @code{FALSE} is returned if closing the file fails, @code{TRUE} is
  37 returned if all is well.
  38
  39 @findex bfd_cache_close_all
  40 @subsubsection @code{bfd_cache_close_all}
  41 @strong{Synopsis}
  42 @example
  43 bfd_boolean bfd_cache_close_all (void);
  44 @end example
  45 @strong{Description}@*
  46 Remove all BFDs from the cache. If the attached file is open,
  47 then close it too.
  48
  49 @strong{Returns}@*
  50 @code{FALSE} is returned if closing one of the file fails, @code{TRUE} is
  51 returned if all is well.
  52
  53 @findex bfd_open_file
  54 @subsubsection @code{bfd_open_file}
  55 @strong{Synopsis}
  56 @example
  57 FILE* bfd_open_file (bfd *abfd);
  58 @end example
  59 @strong{Description}@*
  60 Call the OS to open a file for @var{abfd}.  Return the @code{FILE *}
  61 (possibly @code{NULL}) that results from this operation.  Set up the
  62 BFD so that future accesses know the file is open. If the @code{FILE *}
  63 returned is @code{NULL}, then it won't have been put in the
  64 cache, so it won't have to be removed from it.
  65