GNU Info

(bfd.info)Archives

---

Next: Formats Prev: Symbols Up: BFD front end

---

Enter node , (file) or (file)node

Archives
========

   *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 `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 `next'
pointer in a BFD.  The first one is findable through the `archive_head'
slot of the archive.  Set it with `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 `archive.c'.

`bfd_get_next_mapent'
.....................

   *Synopsis*
     symindex bfd_get_next_mapent(bfd *abfd, symindex previous, carsym **sym);
   *Description*
Step through archive ABFD's symbol table (if it has one).  Successively
update SYM with the next symbol's information, returning that symbol's
(internal) index into the symbol table.

   Supply `BFD_NO_MORE_SYMBOLS' as the PREVIOUS entry to get the first
one; returns `BFD_NO_MORE_SYMBOLS' when you've already got the last one.

   A `carsym' is a canonical archive symbol.  The only user-visible
element is its name, a null-terminated string.

`bfd_set_archive_head'
......................

   *Synopsis*
     boolean bfd_set_archive_head(bfd *output, bfd *new_head);
   *Description*
Set the head of the chain of BFDs contained in the archive OUTPUT to
NEW_HEAD.

`bfd_openr_next_archived_file'
..............................

   *Synopsis*
     bfd *bfd_openr_next_archived_file(bfd *archive, bfd *previous);
   *Description*
Provided a BFD, 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.