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