contrib/binutils/bfd/doc/archive.texi

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