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 21A BFD returned by @code{bfd_openr_next_archived_file} can be 22closed manually with @code{bfd_close}. If you do not close it, 23then a second iteration through the members of an archive may 24return the same BFD. If you close the archive BFD, then all 25the member BFDs will automatically be closed as well. 26 27Archive contents of output BFDs are chained through the 28@code{archive_next} pointer in a BFD. The first one is findable 29through the @code{archive_head} slot of the archive. Set it with 30@code{bfd_set_archive_head} (q.v.). A given BFD may be in only 31one open output archive at a time. 32 33As expected, the BFD archive code is more general than the 34archive code of any given environment. BFD archives may 35contain files of different formats (e.g., a.out and coff) and 36even different architectures. You may even place archives 37recursively into archives! 38 39This can cause unexpected confusion, since some archive 40formats are more expressive than others. For instance, Intel 41COFF archives can preserve long filenames; SunOS a.out archives 42cannot. If you move a file from the first to the second 43format and back again, the filename may be truncated. 44Likewise, different a.out environments have different 45conventions as to how they truncate filenames, whether they 46preserve directory names in filenames, etc. When 47interoperating with native tools, be sure your files are 48homogeneous. 49 50Beware: most of these formats do not react well to the 51presence of spaces in filenames. We do the best we can, but 52can't always handle this case due to restrictions in the format of 53archives. Many Unix utilities are braindead in regards to 54spaces and such in filenames anyway, so this shouldn't be much 55of a restriction. 56 57Archives are supported in BFD in @code{archive.c}. 58 59@subsection Archive functions 60 61 62@findex bfd_get_next_mapent 63@subsubsection @code{bfd_get_next_mapent} 64@strong{Synopsis} 65@example 66symindex bfd_get_next_mapent 67 (bfd *abfd, symindex previous, carsym **sym); 68@end example 69@strong{Description}@* 70Step through archive @var{abfd}'s symbol table (if it 71has one). Successively update @var{sym} with the next symbol's 72information, returning that symbol's (internal) index into the 73symbol table. 74 75Supply @code{BFD_NO_MORE_SYMBOLS} as the @var{previous} entry to get 76the first one; returns @code{BFD_NO_MORE_SYMBOLS} when you've already 77got the last one. 78 79A @code{carsym} is a canonical archive symbol. The only 80user-visible element is its name, a null-terminated string. 81 82@findex bfd_set_archive_head 83@subsubsection @code{bfd_set_archive_head} 84@strong{Synopsis} 85@example 86bool bfd_set_archive_head (bfd *output, bfd *new_head); 87@end example 88@strong{Description}@* 89Set the head of the chain of 90BFDs contained in the archive @var{output} to @var{new_head}. 91 92@findex bfd_openr_next_archived_file 93@subsubsection @code{bfd_openr_next_archived_file} 94@strong{Synopsis} 95@example 96bfd *bfd_openr_next_archived_file (bfd *archive, bfd *previous); 97@end example 98@strong{Description}@* 99Provided a BFD, @var{archive}, containing an archive and NULL, open 100an input BFD on the first contained element and returns that. 101Subsequent calls should pass the archive and the previous return 102value to return a created BFD to the next contained element. NULL 103is returned when there are no more. 104Note - if you want to process the bfd returned by this call be 105sure to call bfd_check_format() on it first. 106 107