* doc/Makefile.am (AM_MAKEINFOFLAGS, TEXI2DVI): Include
[binutils.git] / bfd / doc / cache.texi
blob5820a2a6a1d376e5f40a756bb4bec527c3f75933
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.
13 @subsection Caching functions
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.
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.
35 @strong{Returns}@*
36 @code{FALSE} is returned if closing the file fails, @code{TRUE} is
37 returned if all is well.
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.
49 @strong{Returns}@*
50 @code{FALSE} is returned if closing one of the file fails, @code{TRUE} is
51 returned if all is well.
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.