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 LLVM_BITCODE_ARCHIVE_H 18 #define LLVM_BITCODE_ARCHIVE_H 19 20 #include "llvm/ADT/ilist.h" 21 #include "llvm/ADT/ilist_node.h" 22 #include "llvm/Support/Path.h" 23 #include <map> 24 #include <set> 25 26 namespace llvm { 27 class MemoryBuffer; 28 29 // Forward declare classes 30 class Module; // From VMCore 31 class Archive; // Declared below 32 class ArchiveMemberHeader; // Internal implementation class 33 class LLVMContext; // Global data 34 35 /// This class is the main class manipulated by users of the Archive class. It 36 /// holds information about one member of the Archive. It is also the element 37 /// stored by the Archive's ilist, the Archive's main abstraction. Because of 38 /// the special requirements of archive files, users are not permitted to 39 /// construct ArchiveMember instances. You should obtain them from the methods 40 /// of the Archive class instead. 41 /// @brief This class represents a single archive member. 42 class ArchiveMember : public ilist_node<ArchiveMember> { 43 /// @name Types 44 /// @{ 45 public: 46 /// These flags are used internally by the archive member to specify various 47 /// characteristics of the member. The various "is" methods below provide 48 /// access to the flags. The flags are not user settable. 49 enum Flags { 50 CompressedFlag = 1, ///< Member is a normal compressed file 51 SVR4SymbolTableFlag = 2, ///< Member is a SVR4 symbol table 52 BSD4SymbolTableFlag = 4, ///< Member is a BSD4 symbol table 53 LLVMSymbolTableFlag = 8, ///< Member is an LLVM symbol table 54 BitcodeFlag = 16, ///< Member is bitcode 55 HasPathFlag = 64, ///< Member has a full or partial path 56 HasLongFilenameFlag = 128, ///< Member uses the long filename syntax 57 StringTableFlag = 256 ///< 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 const sys::Path& 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 info.getUser(); } 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 info.getGroup(); } 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 info.getMode(); } 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 info.getTimestamp(); } 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 info.getSize(); } 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 /// This method determines if the member is a regular compressed file. 113 /// @returns true iff the archive member is a compressed regular file. 114 /// @brief Determine if the member is a compressed regular file. 115 bool isCompressed() const { return flags&CompressedFlag; } 116 117 /// @returns true iff the member is a SVR4 (non-LLVM) symbol table 118 /// @brief Determine if this member is a SVR4 symbol table. 119 bool isSVR4SymbolTable() const { return flags&SVR4SymbolTableFlag; } 120 121 /// @returns true iff the member is a BSD4.4 (non-LLVM) symbol table 122 /// @brief Determine if this member is a BSD4.4 symbol table. 123 bool isBSD4SymbolTable() const { return flags&BSD4SymbolTableFlag; } 124 125 /// @returns true iff the archive member is the LLVM symbol table 126 /// @brief Determine if this member is the LLVM symbol table. 127 bool isLLVMSymbolTable() const { return flags&LLVMSymbolTableFlag; } 128 129 /// @returns true iff the archive member is the ar(1) string table 130 /// @brief Determine if this member is the ar(1) string table. 131 bool isStringTable() const { return flags&StringTableFlag; } 132 133 /// @returns true iff the archive member is a bitcode file. 134 /// @brief Determine if this member is a bitcode file. 135 bool isBitcode() const { return flags&BitcodeFlag; } 136 137 /// @returns true iff the file name contains a path (directory) component. 138 /// @brief Determine if the member has a path 139 bool hasPath() const { return flags&HasPathFlag; } 140 141 /// Long filenames are an artifact of the ar(1) file format which allows 142 /// up to sixteen characters in its header and doesn't allow a path 143 /// separator character (/). To avoid this, a "long format" member name is 144 /// allowed that doesn't have this restriction. This method determines if 145 /// that "long format" is used for this member. 146 /// @returns true iff the file name uses the long form 147 /// @brief Determine if the member has a long file name 148 bool hasLongFilename() const { return flags&HasLongFilenameFlag; } 149 150 /// This method returns the status info (like Unix stat(2)) for the archive 151 /// member. The status info provides the file's size, permissions, and 152 /// modification time. The contents of the Path::StatusInfo structure, other 153 /// than the size and modification time, may not have utility on non-Unix 154 /// systems. 155 /// @returns the status info for the archive member 156 /// @brief Obtain the status info for the archive member 157 const sys::FileStatus &getFileStatus() const { return info; } 158 159 /// This method causes the archive member to be replaced with the contents 160 /// of the file specified by \p File. The contents of \p this will be 161 /// updated to reflect the new data from \p File. The \p File must exist and 162 /// be readable on entry to this method. 163 /// @returns true if an error occurred, false otherwise 164 /// @brief Replace contents of archive member with a new file. 165 bool replaceWith(const sys::Path &aFile, std::string* ErrMsg); 166 167 /// @} 168 /// @name Data 169 /// @{ 170 private: 171 Archive* parent; ///< Pointer to parent archive 172 sys::PathWithStatus path; ///< Path of file containing the member 173 sys::FileStatus info; ///< Status info (size,mode,date) 174 unsigned flags; ///< Flags about the archive member 175 const char* data; ///< Data for the member 176 177 /// @} 178 /// @name Constructors 179 /// @{ 180 public: 181 /// The default constructor is only used by the Archive's iplist when it 182 /// constructs the list's sentry node. 183 ArchiveMember(); 184 185 private: 186 /// Used internally by the Archive class to construct an ArchiveMember. 187 /// The contents of the ArchiveMember are filled out by the Archive class. 188 explicit ArchiveMember(Archive *PAR); 189 190 // So Archive can construct an ArchiveMember 191 friend class llvm::Archive; 192 /// @} 193 }; 194 195 /// This class defines the interface to LLVM Archive files. The Archive class 196 /// presents the archive file as an ilist of ArchiveMember objects. The members 197 /// can be rearranged in any fashion either by directly editing the ilist or by 198 /// using editing methods on the Archive class (recommended). The Archive 199 /// class also provides several ways of accessing the archive file for various 200 /// purposes such as editing and linking. Full symbol table support is provided 201 /// for loading only those files that resolve symbols. Note that read 202 /// performance of this library is _crucial_ for performance of JIT type 203 /// applications and the linkers. Consequently, the implementation of the class 204 /// is optimized for reading. 205 class Archive { 206 207 /// @name Types 208 /// @{ 209 public: 210 /// This is the ilist type over which users may iterate to examine 211 /// the contents of the archive 212 /// @brief The ilist type of ArchiveMembers that Archive contains. 213 typedef iplist<ArchiveMember> MembersList; 214 215 /// @brief Forward mutable iterator over ArchiveMember 216 typedef MembersList::iterator iterator; 217 218 /// @brief Forward immutable iterator over ArchiveMember 219 typedef MembersList::const_iterator const_iterator; 220 221 /// @brief Reverse mutable iterator over ArchiveMember 222 typedef std::reverse_iterator<iterator> reverse_iterator; 223 224 /// @brief Reverse immutable iterator over ArchiveMember 225 typedef std::reverse_iterator<const_iterator> const_reverse_iterator; 226 227 /// @brief The in-memory version of the symbol table 228 typedef std::map<std::string,unsigned> SymTabType; 229 230 /// @} 231 /// @name ilist accessor methods 232 /// @{ 233 public: 234 inline iterator begin() { return members.begin(); } 235 inline const_iterator begin() const { return members.begin(); } 236 inline iterator end () { return members.end(); } 237 inline const_iterator end () const { return members.end(); } 238 239 inline reverse_iterator rbegin() { return members.rbegin(); } 240 inline const_reverse_iterator rbegin() const { return members.rbegin(); } 241 inline reverse_iterator rend () { return members.rend(); } 242 inline const_reverse_iterator rend () const { return members.rend(); } 243 244 inline size_t size() const { return members.size(); } 245 inline bool empty() const { return members.empty(); } 246 inline const ArchiveMember& front() const { return members.front(); } 247 inline ArchiveMember& front() { return members.front(); } 248 inline const ArchiveMember& back() const { return members.back(); } 249 inline ArchiveMember& back() { return members.back(); } 250 251 /// @} 252 /// @name ilist mutator methods 253 /// @{ 254 public: 255 /// This method splices a \p src member from an archive (possibly \p this), 256 /// to a position just before the member given by \p dest in \p this. When 257 /// the archive is written, \p src will be written in its new location. 258 /// @brief Move a member to a new location 259 inline void splice(iterator dest, Archive& arch, iterator src) 260 { return members.splice(dest,arch.members,src); } 261 262 /// This method erases a \p target member from the archive. When the 263 /// archive is written, it will no longer contain \p target. The associated 264 /// ArchiveMember is deleted. 265 /// @brief Erase a member. 266 inline iterator erase(iterator target) { return members.erase(target); } 267 268 /// @} 269 /// @name Constructors 270 /// @{ 271 public: 272 /// Create an empty archive file and associate it with the \p Filename. This 273 /// method does not actually create the archive disk file. It creates an 274 /// empty Archive object. If the writeToDisk method is called, the archive 275 /// file \p Filename will be created at that point, with whatever content 276 /// the returned Archive object has at that time. 277 /// @returns An Archive* that represents the new archive file. 278 /// @brief Create an empty Archive. 279 static Archive* CreateEmpty( 280 const sys::Path& Filename,///< Name of the archive to (eventually) create. 281 LLVMContext& C ///< Context to use for global information 282 ); 283 284 /// Open an existing archive and load its contents in preparation for 285 /// editing. After this call, the member ilist is completely populated based 286 /// on the contents of the archive file. You should use this form of open if 287 /// you intend to modify the archive or traverse its contents (e.g. for 288 /// printing). 289 /// @brief Open and load an archive file 290 static Archive* OpenAndLoad( 291 const sys::Path& filePath, ///< The file path to open and load 292 LLVMContext& C, ///< The context to use for global information 293 std::string* ErrorMessage ///< An optional error string 294 ); 295 296 /// This method opens an existing archive file from \p Filename and reads in 297 /// its symbol table without reading in any of the archive's members. This 298 /// reduces both I/O and cpu time in opening the archive if it is to be used 299 /// solely for symbol lookup (e.g. during linking). The \p Filename must 300 /// exist and be an archive file or an error will be returned. This form 301 /// of opening the archive is intended for read-only operations that need to 302 /// locate members via the symbol table for link editing. Since the archve 303 /// members are not read by this method, the archive will appear empty upon 304 /// return. If editing operations are performed on the archive, they will 305 /// completely replace the contents of the archive! It is recommended that 306 /// if this form of opening the archive is used that only the symbol table 307 /// lookup methods (getSymbolTable, findModuleDefiningSymbol, and 308 /// findModulesDefiningSymbols) be used. 309 /// @returns an Archive* that represents the archive file, or null on error. 310 /// @brief Open an existing archive and load its symbols. 311 static Archive* OpenAndLoadSymbols( 312 const sys::Path& Filename, ///< Name of the archive file to open 313 LLVMContext& C, ///< The context to use for global info 314 std::string* ErrorMessage=0 ///< An optional error string 315 ); 316 317 /// This destructor cleans up the Archive object, releases all memory, and 318 /// closes files. It does nothing with the archive file on disk. If you 319 /// haven't used the writeToDisk method by the time the destructor is 320 /// called, all changes to the archive will be lost. 321 /// @brief Destruct in-memory archive 322 ~Archive(); 323 324 /// @} 325 /// @name Accessors 326 /// @{ 327 public: 328 /// @returns the path to the archive file. 329 /// @brief Get the archive path. 330 const sys::Path& getPath() { return archPath; } 331 332 /// This method is provided so that editing methods can be invoked directly 333 /// on the Archive's iplist of ArchiveMember. However, it is recommended 334 /// that the usual STL style iterator interface be used instead. 335 /// @returns the iplist of ArchiveMember 336 /// @brief Get the iplist of the members 337 MembersList& getMembers() { return members; } 338 339 /// This method allows direct query of the Archive's symbol table. The 340 /// symbol table is a std::map of std::string (the symbol) to unsigned (the 341 /// file offset). Note that for efficiency reasons, the offset stored in 342 /// the symbol table is not the actual offset. It is the offset from the 343 /// beginning of the first "real" file member (after the symbol table). Use 344 /// the getFirstFileOffset() to obtain that offset and add this value to the 345 /// offset in the symbol table to obtain the real file offset. Note that 346 /// there is purposefully no interface provided by Archive to look up 347 /// members by their offset. Use the findModulesDefiningSymbols and 348 /// findModuleDefiningSymbol methods instead. 349 /// @returns the Archive's symbol table. 350 /// @brief Get the archive's symbol table 351 const SymTabType& getSymbolTable() { return symTab; } 352 353 /// This method returns the offset in the archive file to the first "real" 354 /// file member. Archive files, on disk, have a signature and might have a 355 /// symbol table that precedes the first actual file member. This method 356 /// allows you to determine what the size of those fields are. 357 /// @returns the offset to the first "real" file member in the archive. 358 /// @brief Get the offset to the first "real" file member in the archive. 359 unsigned getFirstFileOffset() { return firstFileOffset; } 360 361 /// This method will scan the archive for bitcode modules, interpret them 362 /// and return a vector of the instantiated modules in \p Modules. If an 363 /// error occurs, this method will return true. If \p ErrMessage is not null 364 /// and an error occurs, \p *ErrMessage will be set to a string explaining 365 /// the error that occurred. 366 /// @returns true if an error occurred 367 /// @brief Instantiate all the bitcode modules located in the archive 368 bool getAllModules(std::vector<Module*>& Modules, std::string* ErrMessage); 369 370 /// This accessor looks up the \p symbol in the archive's symbol table and 371 /// returns the associated module that defines that symbol. This method can 372 /// be called as many times as necessary. This is handy for linking the 373 /// archive into another module based on unresolved symbols. Note that the 374 /// Module returned by this accessor should not be deleted by the caller. It 375 /// is managed internally by the Archive class. It is possible that multiple 376 /// calls to this accessor will return the same Module instance because the 377 /// associated module defines multiple symbols. 378 /// @returns The Module* found or null if the archive does not contain a 379 /// module that defines the \p symbol. 380 /// @brief Look up a module by symbol name. 381 Module* findModuleDefiningSymbol( 382 const std::string& symbol, ///< Symbol to be sought 383 std::string* ErrMessage ///< Error message storage, if non-zero 384 ); 385 386 /// This method is similar to findModuleDefiningSymbol but allows lookup of 387 /// more than one symbol at a time. If \p symbols contains a list of 388 /// undefined symbols in some module, then calling this method is like 389 /// making one complete pass through the archive to resolve symbols but is 390 /// more efficient than looking at the individual members. Note that on 391 /// exit, the symbols resolved by this method will be removed from \p 392 /// symbols to ensure they are not re-searched on a subsequent call. If 393 /// you need to retain the list of symbols, make a copy. 394 /// @brief Look up multiple symbols in the archive. 395 bool findModulesDefiningSymbols( 396 std::set<std::string>& symbols, ///< Symbols to be sought 397 std::set<Module*>& modules, ///< The modules matching \p symbols 398 std::string* ErrMessage ///< Error msg storage, if non-zero 399 ); 400 401 /// This method determines whether the archive is a properly formed llvm 402 /// bitcode archive. It first makes sure the symbol table has been loaded 403 /// and has a non-zero size. If it does, then it is an archive. If not, 404 /// then it tries to load all the bitcode modules of the archive. Finally, 405 /// it returns whether it was successful. 406 /// @returns true if the archive is a proper llvm bitcode archive 407 /// @brief Determine whether the archive is a proper llvm bitcode archive. 408 bool isBitcodeArchive(); 409 410 /// @} 411 /// @name Mutators 412 /// @{ 413 public: 414 /// This method is the only way to get the archive written to disk. It 415 /// creates or overwrites the file specified when \p this was created 416 /// or opened. The arguments provide options for writing the archive. If 417 /// \p CreateSymbolTable is true, the archive is scanned for bitcode files 418 /// and a symbol table of the externally visible function and global 419 /// variable names is created. If \p TruncateNames is true, the names of the 420 /// archive members will have their path component stripped and the file 421 /// name will be truncated at 15 characters. If \p Compress is specified, 422 /// all archive members will be compressed before being written. If 423 /// \p PrintSymTab is true, the symbol table will be printed to std::cout. 424 /// @returns true if an error occurred, \p error set to error message 425 /// @returns false if the writing succeeded. 426 /// @brief Write (possibly modified) archive contents to disk 427 bool writeToDisk( 428 bool CreateSymbolTable=false, ///< Create Symbol table 429 bool TruncateNames=false, ///< Truncate the filename to 15 chars 430 bool Compress=false, ///< Compress files 431 std::string* ErrMessage=0 ///< If non-null, where error msg is set 432 ); 433 434 /// This method adds a new file to the archive. The \p filename is examined 435 /// to determine just enough information to create an ArchiveMember object 436 /// which is then inserted into the Archive object's ilist at the location 437 /// given by \p where. 438 /// @returns true if an error occurred, false otherwise 439 /// @brief Add a file to the archive. 440 bool addFileBefore( 441 const sys::Path& filename, ///< The file to be added 442 iterator where, ///< Insertion point 443 std::string* ErrMsg ///< Optional error message location 444 ); 445 446 /// @} 447 /// @name Implementation 448 /// @{ 449 protected: 450 /// @brief Construct an Archive for \p filename and optionally map it 451 /// into memory. 452 explicit Archive(const sys::Path& filename, LLVMContext& C); 453 454 /// @param data The symbol table data to be parsed 455 /// @param len The length of the symbol table data 456 /// @param error Set to address of a std::string to get error messages 457 /// @returns false on error 458 /// @brief Parse the symbol table at \p data. 459 bool parseSymbolTable(const void* data,unsigned len,std::string* error); 460 461 /// @returns A fully populated ArchiveMember or 0 if an error occurred. 462 /// @brief Parse the header of a member starting at \p At 463 ArchiveMember* parseMemberHeader( 464 const char*&At, ///< The pointer to the location we're parsing 465 const char*End, ///< The pointer to the end of the archive 466 std::string* error ///< Optional error message catcher 467 ); 468 469 /// @param ErrMessage Set to address of a std::string to get error messages 470 /// @returns false on error 471 /// @brief Check that the archive signature is correct 472 bool checkSignature(std::string* ErrMessage); 473 474 /// @param ErrMessage Set to address of a std::string to get error messages 475 /// @returns false on error 476 /// @brief Load the entire archive. 477 bool loadArchive(std::string* ErrMessage); 478 479 /// @param ErrMessage Set to address of a std::string to get error messages 480 /// @returns false on error 481 /// @brief Load just the symbol table. 482 bool loadSymbolTable(std::string* ErrMessage); 483 484 /// @brief Write the symbol table to an ofstream. 485 void writeSymbolTable(std::ofstream& ARFile); 486 487 /// Writes one ArchiveMember to an ofstream. If an error occurs, returns 488 /// false, otherwise true. If an error occurs and error is non-null then 489 /// it will be set to an error message. 490 /// @returns false Writing member succeeded 491 /// @returns true Writing member failed, \p error set to error message 492 bool writeMember( 493 const ArchiveMember& member, ///< The member to be written 494 std::ofstream& ARFile, ///< The file to write member onto 495 bool CreateSymbolTable, ///< Should symbol table be created? 496 bool TruncateNames, ///< Should names be truncated to 11 chars? 497 bool ShouldCompress, ///< Should the member be compressed? 498 std::string* ErrMessage ///< If non-null, place were error msg is set 499 ); 500 501 /// @brief Fill in an ArchiveMemberHeader from ArchiveMember. 502 bool fillHeader(const ArchiveMember&mbr, 503 ArchiveMemberHeader& hdr,int sz, bool TruncateNames) const; 504 505 /// @brief Maps archive into memory 506 bool mapToMemory(std::string* ErrMsg); 507 508 /// @brief Frees all the members and unmaps the archive file. 509 void cleanUpMemory(); 510 511 /// This type is used to keep track of bitcode modules loaded from the 512 /// symbol table. It maps the file offset to a pair that consists of the 513 /// associated ArchiveMember and the Module. 514 /// @brief Module mapping type 515 typedef std::map<unsigned,std::pair<Module*,ArchiveMember*> > 516 ModuleMap; 517 518 519 /// @} 520 /// @name Data 521 /// @{ 522 protected: 523 sys::Path archPath; ///< Path to the archive file we read/write 524 MembersList members; ///< The ilist of ArchiveMember 525 MemoryBuffer *mapfile; ///< Raw Archive contents mapped into memory 526 const char* base; ///< Base of the memory mapped file data 527 SymTabType symTab; ///< The symbol table 528 std::string strtab; ///< The string table for long file names 529 unsigned symTabSize; ///< Size in bytes of symbol table 530 unsigned firstFileOffset; ///< Offset to first normal file. 531 ModuleMap modules; ///< The modules loaded via symbol lookup. 532 ArchiveMember* foreignST; ///< This holds the foreign symbol table. 533 LLVMContext& Context; ///< This holds global data. 534 /// @} 535 /// @name Hidden 536 /// @{ 537 private: 538 Archive(); ///< Do not implement 539 Archive(const Archive&); ///< Do not implement 540 Archive& operator=(const Archive&); ///< Do not implement 541 /// @} 542 }; 543 544 } // End llvm namespace 545 546 #endif 547
