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