1@section Archives
2
3
4@strong{Description}@*
5An archive (or library) is just another BFD.  It has a symbol
6table, although there's not much a user program will do with it.
7
8The big difference between an archive BFD and an ordinary BFD
9is that the archive doesn't have sections.  Instead it has a
10chain of BFDs that are considered its contents.  These BFDs can
11be manipulated like any other.  The BFDs contained in an
12archive opened for reading will all be opened for reading.  You
13may put either input or output BFDs into an archive opened for
14output; they will be handled correctly when the archive is closed.
15
16Use @code{bfd_openr_next_archived_file} to step through
17the contents of an archive opened for input.  You don't
18have to read the entire archive if you don't want
19to!  Read it until you find what you want.
20
21Archive contents of output BFDs are chained through the
22@code{next} pointer in a BFD.  The first one is findable through
23the @code{archive_head} slot of the archive.  Set it with
24@code{bfd_set_archive_head} (q.v.).  A given BFD may be in only one
25open output archive at a time.
26
27As expected, the BFD archive code is more general than the
28archive code of any given environment.  BFD archives may
29contain files of different formats (e.g., a.out and coff) and
30even different architectures.  You may even place archives
31recursively into archives!
32
33This can cause unexpected confusion, since some archive
34formats are more expressive than others.  For instance, Intel
35COFF archives can preserve long filenames; SunOS a.out archives
36cannot.  If you move a file from the first to the second
37format and back again, the filename may be truncated.
38Likewise, different a.out environments have different
39conventions as to how they truncate filenames, whether they
40preserve directory names in filenames, etc.  When
41interoperating with native tools, be sure your files are
42homogeneous.
43
44Beware: most of these formats do not react well to the
45presence of spaces in filenames.  We do the best we can, but
46can't always handle this case due to restrictions in the format of
47archives.  Many Unix utilities are braindead in regards to
48spaces and such in filenames anyway, so this shouldn't be much
49of a restriction.
50
51Archives are supported in BFD in @code{archive.c}.
52
53@subsection Archive functions
54
55
56@findex bfd_get_next_mapent
57@subsubsection @code{bfd_get_next_mapent}
58@strong{Synopsis}
59@example
60symindex bfd_get_next_mapent
61   (bfd *abfd, symindex previous, carsym **sym);
62@end example
63@strong{Description}@*
64Step through archive @var{abfd}'s symbol table (if it
65has one).  Successively update @var{sym} with the next symbol's
66information, returning that symbol's (internal) index into the
67symbol table.
68
69Supply @code{BFD_NO_MORE_SYMBOLS} as the @var{previous} entry to get
70the first one; returns @code{BFD_NO_MORE_SYMBOLS} when you've already
71got the last one.
72
73A @code{carsym} is a canonical archive symbol.  The only
74user-visible element is its name, a null-terminated string.
75
76@findex bfd_set_archive_head
77@subsubsection @code{bfd_set_archive_head}
78@strong{Synopsis}
79@example
80bfd_boolean bfd_set_archive_head (bfd *output, bfd *new_head);
81@end example
82@strong{Description}@*
83Set the head of the chain of
84BFDs contained in the archive @var{output} to @var{new_head}.
85
86@findex bfd_openr_next_archived_file
87@subsubsection @code{bfd_openr_next_archived_file}
88@strong{Synopsis}
89@example
90bfd *bfd_openr_next_archived_file (bfd *archive, bfd *previous);
91@end example
92@strong{Description}@*
93Provided a BFD, @var{archive}, containing an archive and NULL, open
94an input BFD on the first contained element and returns that.
95Subsequent calls should pass
96the archive and the previous return value to return a created
97BFD to the next contained element. NULL is returned when there
98are no more.
99
100