| @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. |
| |