tools/llvm-ar/Archive.h

   1 //===-- llvm/Bitcode/Archive.h - LLVM Bitcode Archive -----------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This header file declares the Archive and ArchiveMember classes that provide
  11 // manipulation of LLVM Archive files.  The implementation is provided by the
  12 // lib/Bitcode/Archive library.  This library is used to read and write
  13 // archive (*.a) files that contain LLVM bitcode files (or others).
  14 //
  15 //===----------------------------------------------------------------------===//
  16
  17 #ifndef TOOLS_LLVM_AR_ARCHIVE_H
  18 #define TOOLS_LLVM_AR_ARCHIVE_H
  19
  20 #include "llvm/ADT/ilist.h"
  21 #include "llvm/ADT/ilist_node.h"
  22 #include "llvm/Support/Path.h"
  23 #include "llvm/Support/raw_ostream.h"
  24 #include "llvm/Support/TimeValue.h"
  25 #include <map>
  26 #include <set>
  27 #include <vector>
  28
  29 namespace llvm {
  30   class MemoryBuffer;
  31
  32 // Forward declare classes
  33 class Module;              // From VMCore
  34 class Archive;             // Declared below
  35 class ArchiveMemberHeader; // Internal implementation class
  36 class LLVMContext;         // Global data
  37
  38 /// This class is the main class manipulated by users of the Archive class. It
  39 /// holds information about one member of the Archive. It is also the element
  40 /// stored by the Archive's ilist, the Archive's main abstraction. Because of
  41 /// the special requirements of archive files, users are not permitted to
  42 /// construct ArchiveMember instances. You should obtain them from the methods
  43 /// of the Archive class instead.
  44 /// @brief This class represents a single archive member.
  45 class ArchiveMember : public ilist_node<ArchiveMember> {
  46   /// @name Types
  47   /// @{
  48   public:
  49     /// These flags are used internally by the archive member to specify various
  50     /// characteristics of the member. The various "is" methods below provide
  51     /// access to the flags. The flags are not user settable.
  52     enum Flags {
  53       SVR4SymbolTableFlag = 1,     ///< Member is a SVR4 symbol table
  54       BSD4SymbolTableFlag = 2,     ///< Member is a BSD4 symbol table
  55       HasLongFilenameFlag = 8,     ///< Member uses the long filename syntax
  56       StringTableFlag     = 16     ///< Member is an ar(1) format string table
  57     };
  58
  59   /// @}
  60   /// @name Accessors
  61   /// @{
  62   public:
  63     /// @returns the parent Archive instance
  64     /// @brief Get the archive associated with this member
  65     Archive* getArchive() const          { return parent; }
  66
  67     /// @returns the path to the Archive's file
  68     /// @brief Get the path to the archive member
  69     StringRef getPath() const     { return path; }
  70
  71     /// The "user" is the owner of the file per Unix security. This may not
  72     /// have any applicability on non-Unix systems but is a required component
  73     /// of the "ar" file format.
  74     /// @brief Get the user associated with this archive member.
  75     unsigned getUser() const             { return User; }
  76
  77     /// The "group" is the owning group of the file per Unix security. This
  78     /// may not have any applicability on non-Unix systems but is a required
  79     /// component of the "ar" file format.
  80     /// @brief Get the group associated with this archive member.
  81     unsigned getGroup() const            { return Group; }
  82
  83     /// The "mode" specifies the access permissions for the file per Unix
  84     /// security. This may not have any applicability on non-Unix systems but is
  85     /// a required component of the "ar" file format.
  86     /// @brief Get the permission mode associated with this archive member.
  87     unsigned getMode() const             { return Mode; }
  88
  89     /// This method returns the time at which the archive member was last
  90     /// modified when it was not in the archive.
  91     /// @brief Get the time of last modification of the archive member.
  92     sys::TimeValue getModTime() const    { return ModTime; }
  93
  94     /// @returns the size of the archive member in bytes.
  95     /// @brief Get the size of the archive member.
  96     uint64_t getSize() const             { return Size; }
  97
  98     /// This method returns the total size of the archive member as it
  99     /// appears on disk. This includes the file content, the header, the
 100     /// long file name if any, and the padding.
 101     /// @brief Get total on-disk member size.
 102     unsigned getMemberSize() const;
 103
 104     /// This method will return a pointer to the in-memory content of the
 105     /// archive member, if it is available. If the data has not been loaded
 106     /// into memory, the return value will be null.
 107     /// @returns a pointer to the member's data.
 108     /// @brief Get the data content of the archive member
 109     const char* getData() const { return data; }
 110
 111     /// @returns true iff the member is a SVR4 (non-LLVM) symbol table
 112     /// @brief Determine if this member is a SVR4 symbol table.
 113     bool isSVR4SymbolTable() const { return flags&SVR4SymbolTableFlag; }
 114
 115     /// @returns true iff the member is a BSD4.4 (non-LLVM) symbol table
 116     /// @brief Determine if this member is a BSD4.4 symbol table.
 117     bool isBSD4SymbolTable() const { return flags&BSD4SymbolTableFlag; }
 118
 119     /// @returns true iff the archive member is the ar(1) string table
 120     /// @brief Determine if this member is the ar(1) string table.
 121     bool isStringTable() const { return flags&StringTableFlag; }
 122
 123     /// Long filenames are an artifact of the ar(1) file format which allows
 124     /// up to sixteen characters in its header and doesn't allow a path
 125     /// separator character (/). To avoid this, a "long format" member name is
 126     /// allowed that doesn't have this restriction. This method determines if
 127     /// that "long format" is used for this member.
 128     /// @returns true iff the file name uses the long form
 129     /// @brief Determine if the member has a long file name
 130     bool hasLongFilename() const { return flags&HasLongFilenameFlag; }
 131
 132     /// This method causes the archive member to be replaced with the contents
 133     /// of the file specified by \p File. The contents of \p this will be
 134     /// updated to reflect the new data from \p File. The \p File must exist and
 135     /// be readable on entry to this method.
 136     /// @returns true if an error occurred, false otherwise
 137     /// @brief Replace contents of archive member with a new file.
 138     bool replaceWith(StringRef aFile, std::string* ErrMsg);
 139
 140   /// @}
 141   /// @name Data
 142   /// @{
 143   private:
 144     Archive *parent;  ///< Pointer to parent archive
 145     std::string path; ///< Path of file containing the member
 146     uint32_t User;
 147     uint32_t Group;
 148     uint32_t Mode;
 149     sys::TimeValue ModTime;
 150     uint64_t Size;
 151     unsigned flags;   ///< Flags about the archive member
 152     const char *data; ///< Data for the member
 153
 154   /// @}
 155   /// @name Constructors
 156   /// @{
 157   public:
 158     /// The default constructor is only used by the Archive's iplist when it
 159     /// constructs the list's sentry node.
 160     ArchiveMember();
 161
 162   private:
 163     /// Used internally by the Archive class to construct an ArchiveMember.
 164     /// The contents of the ArchiveMember are filled out by the Archive class.
 165     explicit ArchiveMember(Archive *PAR);
 166
 167     // So Archive can construct an ArchiveMember
 168     friend class llvm::Archive;
 169   /// @}
 170 };
 171
 172 /// This class defines the interface to LLVM Archive files. The Archive class
 173 /// presents the archive file as an ilist of ArchiveMember objects. The members
 174 /// can be rearranged in any fashion either by directly editing the ilist or by
 175 /// using editing methods on the Archive class (recommended). The Archive
 176 /// class also provides several ways of accessing the archive file for various
 177 /// purposes such as editing and linking.  Full symbol table support is provided
 178 /// for loading only those files that resolve symbols. Note that read
 179 /// performance of this library is _crucial_ for performance of JIT type
 180 /// applications and the linkers. Consequently, the implementation of the class
 181 /// is optimized for reading.
 182 class Archive {
 183
 184   /// @name Types
 185   /// @{
 186   public:
 187     /// This is the ilist type over which users may iterate to examine
 188     /// the contents of the archive
 189     /// @brief The ilist type of ArchiveMembers that Archive contains.
 190     typedef iplist<ArchiveMember> MembersList;
 191
 192     /// @brief Forward mutable iterator over ArchiveMember
 193     typedef MembersList::iterator iterator;
 194
 195     /// @brief Forward immutable iterator over ArchiveMember
 196     typedef MembersList::const_iterator const_iterator;
 197
 198     /// @brief Reverse mutable iterator over ArchiveMember
 199     typedef std::reverse_iterator<iterator> reverse_iterator;
 200
 201     /// @brief Reverse immutable iterator over ArchiveMember
 202     typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
 203
 204     /// @brief The in-memory version of the symbol table
 205     typedef std::map<std::string,unsigned> SymTabType;
 206
 207   /// @}
 208   /// @name ilist accessor methods
 209   /// @{
 210   public:
 211     inline iterator               begin()        { return members.begin();  }
 212     inline const_iterator         begin()  const { return members.begin();  }
 213     inline iterator               end  ()        { return members.end();    }
 214     inline const_iterator         end  ()  const { return members.end();    }
 215
 216     inline reverse_iterator       rbegin()       { return members.rbegin(); }
 217     inline const_reverse_iterator rbegin() const { return members.rbegin(); }
 218     inline reverse_iterator       rend  ()       { return members.rend();   }
 219     inline const_reverse_iterator rend  () const { return members.rend();   }
 220
 221     inline size_t                 size()   const { return members.size();   }
 222     inline bool                   empty()  const { return members.empty();  }
 223     inline const ArchiveMember&   front()  const { return members.front();  }
 224     inline       ArchiveMember&   front()        { return members.front();  }
 225     inline const ArchiveMember&   back()   const { return members.back();   }
 226     inline       ArchiveMember&   back()         { return members.back();   }
 227
 228   /// @}
 229   /// @name ilist mutator methods
 230   /// @{
 231   public:
 232     /// This method splices a \p src member from an archive (possibly \p this),
 233     /// to a position just before the member given by \p dest in \p this. When
 234     /// the archive is written, \p src will be written in its new location.
 235     /// @brief Move a member to a new location
 236     inline void splice(iterator dest, Archive& arch, iterator src)
 237       { return members.splice(dest,arch.members,src); }
 238
 239     /// This method erases a \p target member from the archive. When the
 240     /// archive is written, it will no longer contain \p target. The associated
 241     /// ArchiveMember is deleted.
 242     /// @brief Erase a member.
 243     inline iterator erase(iterator target) { return members.erase(target); }
 244
 245   /// @}
 246   /// @name Constructors
 247   /// @{
 248   public:
 249     /// Create an empty archive file and associate it with the \p Filename. This
 250     /// method does not actually create the archive disk file. It creates an
 251     /// empty Archive object. If the writeToDisk method is called, the archive
 252     /// file \p Filename will be created at that point, with whatever content
 253     /// the returned Archive object has at that time.
 254     /// @returns An Archive* that represents the new archive file.
 255     /// @brief Create an empty Archive.
 256     static Archive *CreateEmpty(
 257         StringRef Filename, ///< Name of the archive to (eventually) create.
 258         LLVMContext &C      ///< Context to use for global information
 259         );
 260
 261     /// Open an existing archive and load its contents in preparation for
 262     /// editing. After this call, the member ilist is completely populated based
 263     /// on the contents of the archive file. You should use this form of open if
 264     /// you intend to modify the archive or traverse its contents (e.g. for
 265     /// printing).
 266     /// @brief Open and load an archive file
 267     static Archive *OpenAndLoad(
 268         StringRef filePath,       ///< The file path to open and load
 269         LLVMContext &C,           ///< The context to use for global information
 270         std::string *ErrorMessage ///< An optional error string
 271         );
 272
 273     /// This destructor cleans up the Archive object, releases all memory, and
 274     /// closes files. It does nothing with the archive file on disk. If you
 275     /// haven't used the writeToDisk method by the time the destructor is
 276     /// called, all changes to the archive will be lost.
 277     /// @brief Destruct in-memory archive
 278     ~Archive();
 279
 280   /// @}
 281   /// @name Accessors
 282   /// @{
 283   public:
 284     /// @returns the path to the archive file.
 285     /// @brief Get the archive path.
 286     StringRef getPath() { return archPath; }
 287
 288     /// This method is provided so that editing methods can be invoked directly
 289     /// on the Archive's iplist of ArchiveMember. However, it is recommended
 290     /// that the usual STL style iterator interface be used instead.
 291     /// @returns the iplist of ArchiveMember
 292     /// @brief Get the iplist of the members
 293     MembersList& getMembers() { return members; }
 294
 295     /// This method returns the offset in the archive file to the first "real"
 296     /// file member. Archive files, on disk, have a signature and might have a
 297     /// symbol table that precedes the first actual file member. This method
 298     /// allows you to determine what the size of those fields are.
 299     /// @returns the offset to the first "real" file member  in the archive.
 300     /// @brief Get the offset to the first "real" file member  in the archive.
 301     unsigned getFirstFileOffset() { return firstFileOffset; }
 302
 303   /// @}
 304   /// @name Mutators
 305   /// @{
 306   public:
 307     /// This method is the only way to get the archive written to disk. It
 308     /// creates or overwrites the file specified when \p this was created
 309     /// or opened. The arguments provide options for writing the archive. If
 310     /// \p CreateSymbolTable is true, the archive is scanned for bitcode files
 311     /// and a symbol table of the externally visible function and global
 312     /// variable names is created. If \p TruncateNames is true, the names of the
 313     /// archive members will have their path component stripped and the file
 314     /// name will be truncated at 15 characters. If \p Compress is specified,
 315     /// all archive members will be compressed before being written. If
 316     /// \p PrintSymTab is true, the symbol table will be printed to std::cout.
 317     /// @returns true if an error occurred, \p error set to error message;
 318     /// returns false if the writing succeeded.
 319     /// @brief Write (possibly modified) archive contents to disk
 320     bool writeToDisk(
 321       std::string* ErrMessage=0       ///< If non-null, where error msg is set
 322     );
 323
 324     /// This method adds a new file to the archive. The \p filename is examined
 325     /// to determine just enough information to create an ArchiveMember object
 326     /// which is then inserted into the Archive object's ilist at the location
 327     /// given by \p where.
 328     /// @returns true if an error occurred, false otherwise
 329     /// @brief Add a file to the archive.
 330     bool addFileBefore(StringRef filename, ///< The file to be added
 331                        iterator where,     ///< Insertion point
 332                        std::string *ErrMsg ///< Optional error message location
 333                        );
 334
 335   /// @}
 336   /// @name Implementation
 337   /// @{
 338   protected:
 339     /// @brief Construct an Archive for \p filename and optionally  map it
 340     /// into memory.
 341     explicit Archive(StringRef filename, LLVMContext& C);
 342
 343     /// @returns A fully populated ArchiveMember or 0 if an error occurred.
 344     /// @brief Parse the header of a member starting at \p At
 345     ArchiveMember* parseMemberHeader(
 346       const char*&At,    ///< The pointer to the location we're parsing
 347       const char*End,    ///< The pointer to the end of the archive
 348       std::string* error ///< Optional error message catcher
 349     );
 350
 351     /// @param ErrMessage Set to address of a std::string to get error messages
 352     /// @returns false on error
 353     /// @brief Check that the archive signature is correct
 354     bool checkSignature(std::string* ErrMessage);
 355
 356     /// @param ErrMessage Set to address of a std::string to get error messages
 357     /// @returns false on error
 358     /// @brief Load the entire archive.
 359     bool loadArchive(std::string* ErrMessage);
 360
 361     /// @param ErrMessage Set to address of a std::string to get error messages
 362     /// @returns false on error
 363     /// @brief Load just the symbol table.
 364     bool loadSymbolTable(std::string* ErrMessage);
 365
 366     /// Writes one ArchiveMember to an ofstream. If an error occurs, returns
 367     /// false, otherwise true. If an error occurs and error is non-null then
 368     /// it will be set to an error message.
 369     /// @returns false if writing member succeeded,
 370     /// returns true if writing member failed, \p error set to error message.
 371     bool writeMember(
 372       const ArchiveMember& member, ///< The member to be written
 373       raw_fd_ostream& ARFile,      ///< The file to write member onto
 374       std::string* ErrMessage      ///< If non-null, place were error msg is set
 375     );
 376
 377     /// @brief Fill in an ArchiveMemberHeader from ArchiveMember.
 378     bool fillHeader(const ArchiveMember&mbr,
 379                     ArchiveMemberHeader& hdr,int sz) const;
 380
 381     /// @brief Maps archive into memory
 382     bool mapToMemory(std::string* ErrMsg);
 383
 384     /// @brief Frees all the members and unmaps the archive file.
 385     void cleanUpMemory();
 386
 387     /// This type is used to keep track of bitcode modules loaded from the
 388     /// symbol table. It maps the file offset to a pair that consists of the
 389     /// associated ArchiveMember and the Module.
 390     /// @brief Module mapping type
 391     typedef std::map<unsigned,std::pair<Module*,ArchiveMember*> >
 392       ModuleMap;
 393
 394
 395   /// @}
 396   /// @name Data
 397   /// @{
 398   protected:
 399     std::string archPath;     ///< Path to the archive file we read/write
 400     MembersList members;      ///< The ilist of ArchiveMember
 401     MemoryBuffer *mapfile;    ///< Raw Archive contents mapped into memory
 402     const char* base;         ///< Base of the memory mapped file data
 403     std::string strtab;       ///< The string table for long file names
 404     unsigned firstFileOffset; ///< Offset to first normal file.
 405     ModuleMap modules;        ///< The modules loaded via symbol lookup.
 406     LLVMContext& Context;     ///< This holds global data.
 407   /// @}
 408   /// @name Hidden
 409   /// @{
 410   private:
 411     Archive() LLVM_DELETED_FUNCTION;
 412     Archive(const Archive&) LLVM_DELETED_FUNCTION;
 413     Archive& operator=(const Archive&) LLVM_DELETED_FUNCTION;
 414   /// @}
 415 };
 416
 417 } // End llvm namespace
 418
 419 #endif