| @section Archives |
| |
| |
| @strong{Description}@* |
| An archive (or library) is just another BFD. It has a symbol |
| table, although there's not much a user program will do with it. |
| |
| The big difference between an archive BFD and an ordinary BFD |
| is that the archive doesn't have sections. Instead it has a |
| chain of BFDs that are considered its contents. These BFDs can |
| be manipulated like any other. The BFDs contained in an |
| archive opened for reading will all be opened for reading. You |
| may put either input or output BFDs into an archive opened for |
| output; they will be handled correctly when the archive is closed. |
| |
| Use @code{bfd_openr_next_archived_file} to step through |
| the contents of an archive opened for input. You don't |
| have to read the entire archive if you don't want |
| to! Read it until you find what you want. |
| |
| Archive contents of output BFDs are chained through the |
| @code{next} pointer in a BFD. The first one is findable through |
| the @code{archive_head} slot of the archive. Set it with |
| @code{bfd_set_archive_head} (q.v.). A given BFD may be in only one |
| open output archive at a time. |
| |
| As expected, the BFD archive code is more general than the |
| archive code of any given environment. BFD archives may |
| contain files of different formats (e.g., a.out and coff) and |
| even different architectures. You may even place archives |
| recursively into archives! |
| |
| This can cause unexpected confusion, since some archive |
| formats are more expressive than others. For instance, Intel |
| COFF archives can preserve long filenames; SunOS a.out archives |
| cannot. If you move a file from the first to the second |
| format and back again, the filename may be truncated. |
| Likewise, different a.out environments have different |
| conventions as to how they truncate filenames, whether they |
| preserve directory names in filenames, etc. When |
| interoperating with native tools, be sure your files are |
| homogeneous. |
| |
| Beware: most of these formats do not react well to the |
| presence of spaces in filenames. We do the best we can, but |
| can't always handle this case due to restrictions in the format of |
| archives. Many Unix utilities are braindead in regards to |
| spaces and such in filenames anyway, so this shouldn't be much |
| of a restriction. |
| |
| Archives are supported in BFD in @code{archive.c}. |
| |
| @subsection Archive functions |
| |
| |
| @findex bfd_get_next_mapent |
| @subsubsection @code{bfd_get_next_mapent} |
| @strong{Synopsis} |
| @example |
| symindex bfd_get_next_mapent |
| (bfd *abfd, symindex previous, carsym **sym); |
| @end example |
| @strong{Description}@* |
| Step through archive @var{abfd}'s symbol table (if it |
| has one). Successively update @var{sym} with the next symbol's |
| information, returning that symbol's (internal) index into the |
| symbol table. |
| |
| Supply @code{BFD_NO_MORE_SYMBOLS} as the @var{previous} entry to get |
| the first one; returns @code{BFD_NO_MORE_SYMBOLS} when you've already |
| got the last one. |
| |
| A @code{carsym} is a canonical archive symbol. The only |
| user-visible element is its name, a null-terminated string. |
| |
| @findex bfd_set_archive_head |
| @subsubsection @code{bfd_set_archive_head} |
| @strong{Synopsis} |
| @example |
| bfd_boolean bfd_set_archive_head (bfd *output, bfd *new_head); |
| @end example |
| @strong{Description}@* |
| Set the head of the chain of |
| BFDs contained in the archive @var{output} to @var{new_head}. |
| |
| @findex bfd_openr_next_archived_file |
| @subsubsection @code{bfd_openr_next_archived_file} |
| @strong{Synopsis} |
| @example |
| bfd *bfd_openr_next_archived_file (bfd *archive, bfd *previous); |
| @end example |
| @strong{Description}@* |
| Provided a BFD, @var{archive}, containing an archive and NULL, open |
| an input BFD on the first contained element and returns that. |
| Subsequent calls should pass |
| the archive and the previous return value to return a created |
| BFD to the next contained element. NULL is returned when there |
| are no more. |
| |