LLVM API Documentation
00001 //===-- llvm/Bytecode/Archive.h - LLVM Bytecode Archive ---------*- C++ -*-===// 00002 // 00003 // The LLVM Compiler Infrastructure 00004 // 00005 // This file was developed by Reid Spencer and is distributed under the 00006 // University of Illinois Open Source License. See LICENSE.TXT for details. 00007 // 00008 //===----------------------------------------------------------------------===// 00009 // 00010 // This header file declares the Archive and ArchiveMember classes that provide 00011 // manipulation of LLVM Archive files. The implementation is provided by the 00012 // lib/Bytecode/Archive library. This library is used to read and write 00013 // archive (*.a) files that contain LLVM bytecode files (or others). 00014 // 00015 //===----------------------------------------------------------------------===// 00016 00017 #ifndef LLVM_BYTECODE_ARCHIVE_H 00018 #define LLVM_BYTECODE_ARCHIVE_H 00019 00020 #include "llvm/ADT/ilist" 00021 #include "llvm/System/Path.h" 00022 #include "llvm/System/MappedFile.h" 00023 #include <map> 00024 #include <set> 00025 #include <fstream> 00026 00027 namespace llvm { 00028 00029 // Forward declare classes 00030 class ModuleProvider; // From VMCore 00031 class Module; // From VMCore 00032 class Archive; // Declared below 00033 class ArchiveMemberHeader; // Internal implementation class 00034 00035 /// This class is the main class manipulated by users of the Archive class. It 00036 /// holds information about one member of the Archive. It is also the element 00037 /// stored by the Archive's ilist, the Archive's main abstraction. Because of 00038 /// the special requirements of archive files, users are not permitted to 00039 /// construct ArchiveMember instances. You should obtain them from the methods 00040 /// of the Archive class instead. 00041 /// @brief This class represents a single archive member. 00042 class ArchiveMember { 00043 00044 /// @name Types 00045 /// @{ 00046 public: 00047 /// These flags are used internally by the archive member to specify various 00048 /// characteristics of the member. The various "is" methods below provide 00049 /// access to the flags. The flags are not user settable. 00050 enum Flags { 00051 CompressedFlag = 1, ///< Member is a normal compressed file 00052 SVR4SymbolTableFlag = 2, ///< Member is a SVR4 symbol table 00053 BSD4SymbolTableFlag = 4, ///< Member is a BSD4 symbol table 00054 LLVMSymbolTableFlag = 8, ///< Member is an LLVM symbol table 00055 BytecodeFlag = 16, ///< Member is uncompressed bytecode 00056 CompressedBytecodeFlag = 32, ///< Member is compressed bytecode 00057 HasPathFlag = 64, ///< Member has a full or partial path 00058 HasLongFilenameFlag = 128, ///< Member uses the long filename syntax 00059 StringTableFlag = 256 ///< Member is an ar(1) format string table 00060 }; 00061 00062 /// @} 00063 /// @name Accessors 00064 /// @{ 00065 public: 00066 /// @returns the parent Archive instance 00067 /// @brief Get the archive associated with this member 00068 Archive* getArchive() const { return parent; } 00069 00070 /// @returns the path to the Archive's file 00071 /// @brief Get the path to the archive member 00072 const sys::Path& getPath() const { return path; } 00073 00074 /// The "user" is the owner of the file per Unix security. This may not 00075 /// have any applicability on non-Unix systems but is a required component 00076 /// of the "ar" file format. 00077 /// @brief Get the user associated with this archive member. 00078 unsigned getUser() const { return info.user; } 00079 00080 /// The "group" is the owning group of the file per Unix security. This 00081 /// may not have any applicability on non-Unix systems but is a required 00082 /// component of the "ar" file format. 00083 /// @brief Get the group associated with this archive member. 00084 unsigned getGroup() const { return info.group; } 00085 00086 /// The "mode" specifies the access permissions for the file per Unix 00087 /// security. This may not have any applicabiity on non-Unix systems but is 00088 /// a required component of the "ar" file format. 00089 /// @brief Get the permission mode associated with this archive member. 00090 unsigned getMode() const { return info.mode; } 00091 00092 /// This method returns the time at which the archive member was last 00093 /// modified when it was not in the archive. 00094 /// @brief Get the time of last modification of the archive member. 00095 sys::TimeValue getModTime() const { return info.modTime; } 00096 00097 /// @returns the size of the archive member in bytes. 00098 /// @brief Get the size of the archive member. 00099 unsigned getSize() const { return info.fileSize; } 00100 00101 /// This method returns the total size of the archive member as it 00102 /// appears on disk. This includes the file content, the header, the 00103 /// long file name if any, and the padding. 00104 /// @brief Get total on-disk member size. 00105 unsigned getMemberSize() const; 00106 00107 /// This method will return a pointer to the in-memory content of the 00108 /// archive member, if it is available. If the data has not been loaded 00109 /// into memory, the return value will be null. 00110 /// @returns a pointer to the member's data. 00111 /// @brief Get the data content of the archive member 00112 const void* getData() const { return data; } 00113 00114 /// This method determines if the member is a regular compressed file. Note 00115 /// that compressed bytecode files will yield "false" for this method. 00116 /// @see isCompressedBytecode() 00117 /// @returns true iff the archive member is a compressed regular file. 00118 /// @brief Determine if the member is a compressed regular file. 00119 bool isCompressed() const { return flags&CompressedFlag; } 00120 00121 /// @returns true iff the member is a SVR4 (non-LLVM) symbol table 00122 /// @brief Determine if this member is a SVR4 symbol table. 00123 bool isSVR4SymbolTable() const { return flags&SVR4SymbolTableFlag; } 00124 00125 /// @returns true iff the member is a BSD4.4 (non-LLVM) symbol table 00126 /// @brief Determine if this member is a BSD4.4 symbol table. 00127 bool isBSD4SymbolTable() const { return flags&BSD4SymbolTableFlag; } 00128 00129 /// @returns true iff the archive member is the LLVM symbol table 00130 /// @brief Determine if this member is the LLVM symbol table. 00131 bool isLLVMSymbolTable() const { return flags&LLVMSymbolTableFlag; } 00132 00133 /// @returns true iff the archive member is the ar(1) string table 00134 /// @brief Determine if this member is the ar(1) string table. 00135 bool isStringTable() const { return flags&StringTableFlag; } 00136 00137 /// @returns true iff the archive member is an uncompressed bytecode file. 00138 /// @brief Determine if this member is a bytecode file. 00139 bool isBytecode() const { return flags&BytecodeFlag; } 00140 00141 /// @returns true iff the archive member is a compressed bytecode file. 00142 /// @brief Determine if the member is a compressed bytecode file. 00143 bool isCompressedBytecode() const { return flags&CompressedBytecodeFlag;} 00144 00145 /// @returns true iff the file name contains a path (directory) component. 00146 /// @brief Determine if the member has a path 00147 bool hasPath() const { return flags&HasPathFlag; } 00148 00149 /// Long filenames are an artifact of the ar(1) file format which allows 00150 /// up to sixteen characters in its header and doesn't allow a path 00151 /// separator character (/). To avoid this, a "long format" member name is 00152 /// allowed that doesn't have this restriction. This method determines if 00153 /// that "long format" is used for this member. 00154 /// @returns true iff the file name uses the long form 00155 /// @brief Determin if the member has a long file name 00156 bool hasLongFilename() const { return flags&HasLongFilenameFlag; } 00157 00158 /// This method returns the status info (like Unix stat(2)) for the archive 00159 /// member. The status info provides the file's size, permissions, and 00160 /// modification time. The contents of the Path::StatusInfo structure, other 00161 /// than the size and modification time, may not have utility on non-Unix 00162 /// systems. 00163 /// @returns the status info for the archive member 00164 /// @brief Obtain the status info for the archive member 00165 const sys::Path::StatusInfo& getStatusInfo() const { return info; } 00166 00167 /// This method causes the archive member to be replaced with the contents 00168 /// of the file specified by \p File. The contents of \p this will be 00169 /// updated to reflect the new data from \p File. The \p File must exist and 00170 /// be readable on entry to this method. 00171 /// @brief Replace contents of archive member with a new file. 00172 void replaceWith(const sys::Path& aFile); 00173 00174 /// @} 00175 /// @name ilist methods - do not use 00176 /// @{ 00177 public: 00178 const ArchiveMember *getNext() const { return next; } 00179 const ArchiveMember *getPrev() const { return prev; } 00180 ArchiveMember *getNext() { return next; } 00181 ArchiveMember *getPrev() { return prev; } 00182 void setPrev(ArchiveMember* p) { prev = p; } 00183 void setNext(ArchiveMember* n) { next = n; } 00184 00185 /// @} 00186 /// @name Data 00187 /// @{ 00188 private: 00189 ArchiveMember* next; ///< Pointer to next archive member 00190 ArchiveMember* prev; ///< Pointer to previous archive member 00191 Archive* parent; ///< Pointer to parent archive 00192 sys::Path path; ///< Path of file containing the member 00193 sys::Path::StatusInfo info; ///< Status info (size,mode,date) 00194 unsigned flags; ///< Flags about the archive member 00195 const void* data; ///< Data for the member 00196 00197 /// @} 00198 /// @name Constructors 00199 /// @{ 00200 public: 00201 /// The default constructor is only used by the Archive's iplist when it 00202 /// constructs the list's sentry node. 00203 ArchiveMember(); 00204 00205 private: 00206 /// Used internally by the Archive class to construct an ArchiveMember. 00207 /// The contents of the ArchiveMember are filled out by the Archive class. 00208 ArchiveMember( Archive* PAR ); 00209 00210 // So Archive can construct an ArchiveMember 00211 friend class llvm::Archive; 00212 /// @} 00213 }; 00214 00215 /// This class defines the interface to LLVM Archive files. The Archive class 00216 /// presents the archive file as an ilist of ArchiveMember objects. The members 00217 /// can be rearranged in any fashion either by directly editing the ilist or by 00218 /// using editing methods on the Archive class (recommended). The Archive 00219 /// class also provides several ways of accessing the archive file for various 00220 /// purposes such as editing and linking. Full symbol table support is provided 00221 /// for loading only those files that resolve symbols. Note that read 00222 /// performance of this library is _crucial_ for performance of JIT type 00223 /// applications and the linkers. Consequently, the implementation of the class 00224 /// is optimized for reading. 00225 class Archive { 00226 00227 /// @name Types 00228 /// @{ 00229 public: 00230 /// This is the ilist type over which users may iterate to examine 00231 /// the contents of the archive 00232 /// @brief The ilist type of ArchiveMembers that Archive contains. 00233 typedef iplist<ArchiveMember> MembersList; 00234 00235 /// @brief Forward mutable iterator over ArchiveMember 00236 typedef MembersList::iterator iterator; 00237 00238 /// @brief Forward immutable iterator over ArchiveMember 00239 typedef MembersList::const_iterator const_iterator; 00240 00241 /// @brief Reverse mutable iterator over ArchiveMember 00242 typedef std::reverse_iterator<iterator> reverse_iterator; 00243 00244 /// @brief Reverse immutable iterator over ArchiveMember 00245 typedef std::reverse_iterator<const_iterator> const_reverse_iterator; 00246 00247 /// @brief The in-memory version of the symbol table 00248 typedef std::map<std::string,unsigned> SymTabType; 00249 00250 /// @} 00251 /// @name ilist accessor methods 00252 /// @{ 00253 public: 00254 inline iterator begin() { return members.begin(); } 00255 inline const_iterator begin() const { return members.begin(); } 00256 inline iterator end () { return members.end(); } 00257 inline const_iterator end () const { return members.end(); } 00258 00259 inline reverse_iterator rbegin() { return members.rbegin(); } 00260 inline const_reverse_iterator rbegin() const { return members.rbegin(); } 00261 inline reverse_iterator rend () { return members.rend(); } 00262 inline const_reverse_iterator rend () const { return members.rend(); } 00263 00264 inline unsigned size() const { return members.size(); } 00265 inline bool empty() const { return members.empty(); } 00266 inline const ArchiveMember& front() const { return members.front(); } 00267 inline ArchiveMember& front() { return members.front(); } 00268 inline const ArchiveMember& back() const { return members.back(); } 00269 inline ArchiveMember& back() { return members.back(); } 00270 00271 /// @} 00272 /// @name ilist mutator methods 00273 /// @{ 00274 public: 00275 /// This method splices a \p src member from an archive (possibly \p this), 00276 /// to a position just before the member given by \p dest in \p this. When 00277 /// the archive is written, \p src will be written in its new location. 00278 /// @brief Move a member to a new location 00279 inline void splice(iterator dest, Archive& arch, iterator src) 00280 { return members.splice(dest,arch.members,src); } 00281 00282 /// This method erases a \p target member from the archive. When the 00283 /// archive is written, it will no longer contain \p target. The associated 00284 /// ArchiveMember is deleted. 00285 /// @brief Erase a member. 00286 inline iterator erase(iterator target) { return members.erase(target); } 00287 00288 /// @} 00289 /// @name Constructors 00290 /// @{ 00291 public: 00292 /// Create an empty archive file and associate it with the \p Filename. This 00293 /// method does not actually create the archive disk file. It creates an 00294 /// empty Archive object. If the writeToDisk method is called, the archive 00295 /// file \p Filename will be created at that point, with whatever content 00296 /// the returned Archive object has at that time. 00297 /// @returns An Archive* that represents the new archive file. 00298 /// @brief Create an empty Archive. 00299 static Archive* CreateEmpty( 00300 const sys::Path& Filename ///< Name of the archive to (eventually) create. 00301 ); 00302 00303 /// Open an existing archive and load its contents in preparation for 00304 /// editing. After this call, the member ilist is completely populated based 00305 /// on the contents of the archive file. You should use this form of open if 00306 /// you intend to modify the archive or traverse its contents (e.g. for 00307 /// printing). 00308 /// @brief Open and load an archive file 00309 static Archive* OpenAndLoad( 00310 const sys::Path& filePath, ///< The file path to open and load 00311 std::string* ErrorMessage = 0 ///< An optional error string 00312 ); 00313 00314 /// This method opens an existing archive file from \p Filename and reads in 00315 /// its symbol table without reading in any of the archive's members. This 00316 /// reduces both I/O and cpu time in opening the archive if it is to be used 00317 /// solely for symbol lookup (e.g. during linking). The \p Filename must 00318 /// exist and be an archive file or an exception will be thrown. This form 00319 /// of opening the archive is intended for read-only operations that need to 00320 /// locate members via the symbol table for link editing. Since the archve 00321 /// members are not read by this method, the archive will appear empty upon 00322 /// return. If editing operations are performed on the archive, they will 00323 /// completely replace the contents of the archive! It is recommended that 00324 /// if this form of opening the archive is used that only the symbol table 00325 /// lookup methods (getSymbolTable, findModuleDefiningSymbol, and 00326 /// findModulesDefiningSymbols) be used. 00327 /// @throws std::string if an error occurs opening the file 00328 /// @returns an Archive* that represents the archive file. 00329 /// @brief Open an existing archive and load its symbols. 00330 static Archive* OpenAndLoadSymbols( 00331 const sys::Path& Filename, ///< Name of the archive file to open 00332 std::string* ErrorMessage=0 ///< An optional error string 00333 ); 00334 00335 /// This destructor cleans up the Archive object, releases all memory, and 00336 /// closes files. It does nothing with the archive file on disk. If you 00337 /// haven't used the writeToDisk method by the time the destructor is 00338 /// called, all changes to the archive will be lost. 00339 /// @throws std::string if an error occurs 00340 /// @brief Destruct in-memory archive 00341 ~Archive(); 00342 00343 /// @} 00344 /// @name Accessors 00345 /// @{ 00346 public: 00347 /// @returns the path to the archive file. 00348 /// @brief Get the archive path. 00349 const sys::Path& getPath() { return archPath; } 00350 00351 /// This method is provided so that editing methods can be invoked directly 00352 /// on the Archive's iplist of ArchiveMember. However, it is recommended 00353 /// that the usual STL style iterator interface be used instead. 00354 /// @returns the iplist of ArchiveMember 00355 /// @brief Get the iplist of the members 00356 MembersList& getMembers() { return members; } 00357 00358 /// This method allows direct query of the Archive's symbol table. The 00359 /// symbol table is a std::map of std::string (the symbol) to unsigned (the 00360 /// file offset). Note that for efficiency reasons, the offset stored in 00361 /// the symbol table is not the actual offset. It is the offset from the 00362 /// beginning of the first "real" file member (after the symbol table). Use 00363 /// the getFirstFileOffset() to obtain that offset and add this value to the 00364 /// offset in the symbol table to obtain the real file offset. Note that 00365 /// there is purposefully no interface provided by Archive to look up 00366 /// members by their offset. Use the findModulesDefiningSymbols and 00367 /// findModuleDefiningSymbol methods instead. 00368 /// @returns the Archive's symbol table. 00369 /// @brief Get the archive's symbol table 00370 const SymTabType& getSymbolTable() { return symTab; } 00371 00372 /// This method returns the offset in the archive file to the first "real" 00373 /// file member. Archive files, on disk, have a signature and might have a 00374 /// symbol table that precedes the first actual file member. This method 00375 /// allows you to determine what the size of those fields are. 00376 /// @returns the offset to the first "real" file member in the archive. 00377 /// @brief Get the offset to the first "real" file member in the archive. 00378 unsigned getFirstFileOffset() { return firstFileOffset; } 00379 00380 /// This method will scan the archive for bytecode modules, interpret them 00381 /// and return a vector of the instantiated modules in \p Modules. If an 00382 /// error occurs, this method will return true. If \p ErrMessage is not null 00383 /// and an error occurs, \p *ErrMessage will be set to a string explaining 00384 /// the error that occurred. 00385 /// @returns true if an error occurred 00386 /// @brief Instantiate all the bytecode modules located in the archive 00387 bool getAllModules(std::vector<Module*>& Modules, std::string* ErrMessage); 00388 00389 /// This accessor looks up the \p symbol in the archive's symbol table and 00390 /// returns the associated module that defines that symbol. This method can 00391 /// be called as many times as necessary. This is handy for linking the 00392 /// archive into another module based on unresolved symbols. Note that the 00393 /// ModuleProvider returned by this accessor should not be deleted by the 00394 /// caller. It is managed internally by the Archive class. It is possible 00395 /// that multiple calls to this accessor will return the same ModuleProvider 00396 /// instance because the associated module defines multiple symbols. 00397 /// @returns The ModuleProvider* found or null if the archive does not 00398 /// contain a module that defines the \p symbol. 00399 /// @brief Look up a module by symbol name. 00400 ModuleProvider* findModuleDefiningSymbol( 00401 const std::string& symbol ///< Symbol to be sought 00402 ); 00403 00404 /// This method is similar to findModuleDefiningSymbol but allows lookup of 00405 /// more than one symbol at a time. If \p symbols contains a list of 00406 /// undefined symbols in some module, then calling this method is like 00407 /// making one complete pass through the archive to resolve symbols but is 00408 /// more efficient than looking at the individual members. Note that on 00409 /// exit, the symbols resolved by this method will be removed from \p 00410 /// symbols to ensure they are not re-searched on a subsequent call. If 00411 /// you need to retain the list of symbols, make a copy. 00412 /// @brief Look up multiple symbols in the archive. 00413 void findModulesDefiningSymbols( 00414 std::set<std::string>& symbols, ///< Symbols to be sought 00415 std::set<ModuleProvider*>& modules ///< The modules matching \p symbols 00416 ); 00417 00418 /// This method determines whether the archive is a properly formed llvm 00419 /// bytecode archive. It first makes sure the symbol table has been loaded 00420 /// and has a non-zero size. If it does, then it is an archive. If not, 00421 /// then it tries to load all the bytecode modules of the archive. Finally, 00422 /// it returns whether it was successfull. 00423 /// @returns true if the archive is a proper llvm bytecode archive 00424 /// @brief Determine whether the archive is a proper llvm bytecode archive. 00425 bool isBytecodeArchive(); 00426 00427 /// @} 00428 /// @name Mutators 00429 /// @{ 00430 public: 00431 /// This method is the only way to get the archive written to disk. It 00432 /// creates or overwrites the file specified when \p this was created 00433 /// or opened. The arguments provide options for writing the archive. If 00434 /// \p CreateSymbolTable is true, the archive is scanned for bytecode files 00435 /// and a symbol table of the externally visible function and global 00436 /// variable names is created. If \p TruncateNames is true, the names of the 00437 /// archive members will have their path component stripped and the file 00438 /// name will be truncated at 15 characters. If \p Compress is specified, 00439 /// all archive members will be compressed before being written. If 00440 /// \p PrintSymTab is true, the symbol table will be printed to std::cout. 00441 /// @throws std::string if an error occurs 00442 /// @brief Write (possibly modified) archive contents to disk 00443 void writeToDisk( 00444 bool CreateSymbolTable=false, ///< Create Symbol table 00445 bool TruncateNames=false, ///< Truncate the filename to 15 chars 00446 bool Compress=false ///< Compress files 00447 ); 00448 00449 /// This method adds a new file to the archive. The \p filename is examined 00450 /// to determine just enough information to create an ArchiveMember object 00451 /// which is then inserted into the Archive object's ilist at the location 00452 /// given by \p where. 00453 /// @throws std::string if an error occurs reading the \p filename. 00454 /// @returns nothing 00455 /// @brief Add a file to the archive. 00456 void addFileBefore(const sys::Path& filename, iterator where); 00457 00458 /// @} 00459 /// @name Implementation 00460 /// @{ 00461 protected: 00462 /// @brief Construct an Archive for \p filename and optionally map it 00463 /// into memory. 00464 Archive(const sys::Path& filename, bool map = false ); 00465 00466 /// @brief Parse the symbol table at \p data. 00467 void parseSymbolTable(const void* data,unsigned len); 00468 00469 /// @brief Parse the header of a member starting at \p At 00470 ArchiveMember* parseMemberHeader(const char*&At,const char*End); 00471 00472 /// @brief Check that the archive signature is correct 00473 void checkSignature(); 00474 00475 /// @brief Load the entire archive. 00476 void loadArchive(); 00477 00478 /// @brief Load just the symbol table. 00479 void loadSymbolTable(); 00480 00481 /// @brief Write the symbol table to an ofstream. 00482 void writeSymbolTable(std::ofstream& ARFile); 00483 00484 /// @brief Write one ArchiveMember to an ofstream. 00485 void writeMember(const ArchiveMember& member, std::ofstream& ARFile, 00486 bool CreateSymbolTable, bool TruncateNames, bool ShouldCompress); 00487 00488 /// @brief Fill in an ArchiveMemberHeader from ArchiveMember. 00489 bool fillHeader(const ArchiveMember&mbr, 00490 ArchiveMemberHeader& hdr,int sz, bool TruncateNames) const; 00491 00492 /// @brief Frees all the members and unmaps the archive file. 00493 void cleanUpMemory(); 00494 00495 /// This type is used to keep track of bytecode modules loaded from the 00496 /// symbol table. It maps the file offset to a pair that consists of the 00497 /// associated ArchiveMember and the ModuleProvider. 00498 /// @brief Module mapping type 00499 typedef std::map<unsigned,std::pair<ModuleProvider*,ArchiveMember*> > 00500 ModuleMap; 00501 00502 /// @} 00503 /// @name Data 00504 /// @{ 00505 protected: 00506 sys::Path archPath; ///< Path to the archive file we read/write 00507 MembersList members; ///< The ilist of ArchiveMember 00508 sys::MappedFile* mapfile; ///< Raw Archive contents mapped into memory 00509 const char* base; ///< Base of the memory mapped file data 00510 SymTabType symTab; ///< The symbol table 00511 std::string strtab; ///< The string table for long file names 00512 unsigned symTabSize; ///< Size in bytes of symbol table 00513 unsigned firstFileOffset; ///< Offset to first normal file. 00514 ModuleMap modules; ///< The modules loaded via symbol lookup. 00515 ArchiveMember* foreignST; ///< This holds the foreign symbol table. 00516 00517 /// @} 00518 /// @name Hidden 00519 /// @{ 00520 private: 00521 Archive(); ///< Do not implement 00522 Archive(const Archive&); ///< Do not implement 00523 Archive& operator=(const Archive&); ///< Do not implement 00524 /// @} 00525 }; 00526 00527 } // End llvm namespace 00528 00529 #endif