1 files changed, 65 insertions, 0 deletions
diff --git a/bfd/doc/cache.texi b/bfd/doc/cache.texi
new file mode 100644
index 00000000000..05b627e6ff9
--- /dev/null
+++ b/bfd/doc/cache.texi
@@ -0,0 +1,65 @@
+@section File caching
+The file caching mechanism is embedded within BFD and allows
+the application to open as many BFDs as it wants without
+regard to the underlying operating system's file descriptor
+limit (often as low as 20 open files).  The module in
+@code{cache.c} maintains a least recently used list of
+@code{bfd_cache_max_open} files, and exports the name
+@code{bfd_cache_lookup}, which runs around and makes sure that
+the required BFD is open. If not, then it chooses a file to
+close, closes it and opens the one wanted, returning its file
+handle.
+
+@subsection Caching functions
+
+
+@findex bfd_cache_init
+@subsubsection @code{bfd_cache_init}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_cache_init (bfd *abfd);
+@end example
+@strong{Description}@*
+Add a newly opened BFD to the cache.
+
+@findex bfd_cache_close
+@subsubsection @code{bfd_cache_close}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_cache_close (bfd *abfd);
+@end example
+@strong{Description}@*
+Remove the BFD @var{abfd} from the cache. If the attached file is open,
+then close it too.
+
+@strong{Returns}@*
+@code{FALSE} is returned if closing the file fails, @code{TRUE} is
+returned if all is well.
+
+@findex bfd_cache_close_all
+@subsubsection @code{bfd_cache_close_all}
+@strong{Synopsis}
+@example
+bfd_boolean bfd_cache_close_all (void);
+@end example
+@strong{Description}@*
+Remove all BFDs from the cache. If the attached file is open,
+then close it too.
+
+@strong{Returns}@*
+@code{FALSE} is returned if closing one of the file fails, @code{TRUE} is
+returned if all is well.
+
+@findex bfd_open_file
+@subsubsection @code{bfd_open_file}
+@strong{Synopsis}
+@example
+FILE* bfd_open_file (bfd *abfd);
+@end example
+@strong{Description}@*
+Call the OS to open a file for @var{abfd}.  Return the @code{FILE *}
+(possibly @code{NULL}) that results from this operation.  Set up the
+BFD so that future accesses know the file is open. If the @code{FILE *}
+returned is @code{NULL}, then it won't have been put in the
+cache, so it won't have to be removed from it.
+