1 files changed, 95 insertions, 0 deletions
diff --git a/contrib/binutils/bfd/doc/cache.texi b/contrib/binutils/bfd/doc/cache.texi
new file mode 100644
index 0000000..badda34
--- /dev/null
+++ b/contrib/binutils/bfd/doc/cache.texi
@@ -0,0 +1,95 @@
+@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.
+@*
+@findex BFD_CACHE_MAX_OPEN macro
+@subsubsection @code{BFD_CACHE_MAX_OPEN macro}
+@strong{Description}@*
+The maximum number of files which the cache will keep open at
+one time.
+@example
+#define BFD_CACHE_MAX_OPEN 10
+@end example
+@*
+@findex bfd_last_cache
+@subsubsection @code{bfd_last_cache}
+@strong{Synopsis}
+@example
+extern bfd *bfd_last_cache;
+@end example
+@strong{Description}@*
+Zero, or a pointer to the topmost BFD on the chain.  This is
+used by the @code{bfd_cache_lookup} macro in @file{libbfd.h} to
+determine when it can avoid a function call.
+@*
+@findex bfd_cache_lookup
+@subsubsection @code{bfd_cache_lookup}
+@strong{Description}@*
+Check to see if the required BFD is the same as the last one
+looked up. If so, then it can use the stream in the BFD with
+impunity, since it can't have changed since the last lookup;
+otherwise, it has to perform the complicated lookup function.
+@example
+#define bfd_cache_lookup(x) \
+    ((x)==bfd_last_cache? \
+      (FILE*)(bfd_last_cache->iostream): \
+       bfd_cache_lookup_worker(x))
+@end example
+@*
+@findex bfd_cache_init
+@subsubsection @code{bfd_cache_init}
+@strong{Synopsis}
+@example
+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
+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_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.
+@*
+@findex bfd_cache_lookup_worker
+@subsubsection @code{bfd_cache_lookup_worker}
+@strong{Synopsis}
+@example
+FILE *bfd_cache_lookup_worker(bfd *abfd);
+@end example
+@strong{Description}@*
+Called when the macro @code{bfd_cache_lookup} fails to find a
+quick answer.  Find a file descriptor for @var{abfd}.  If
+necessary, it open it.  If there are already more than
+@code{BFD_CACHE_MAX_OPEN} files open, it tries to close one first, to
+avoid running out of file descriptors.
+@*