1 //===-- llvm/Bytecode/Archive.h - LLVM Bytecode Archive ---------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file was developed by Reid Spencer and is distributed under the
6 // University of Illinois Open Source License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
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/Bytecode/Archive library. This library is used to read and write
13 // archive (*.a) files that contain LLVM bytecode files (or others).
15 //===----------------------------------------------------------------------===//
17 #ifndef LLVM_BYTECODE_ARCHIVE_H
18 #define LLVM_BYTECODE_ARCHIVE_H
20 #include "llvm/ADT/ilist"
21 #include "llvm/System/Path.h"
22 #include "llvm/System/MappedFile.h"
29 // Forward declare classes
30 class ModuleProvider; // From VMCore
31 class Module; // From VMCore
32 class Archive; // Declared below
33 class ArchiveMemberHeader; // Internal implementation class
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.
47 /// These flags are used internally by the archive member to specify various
48 /// characteristics of the member. The various "is" methods below provide
49 /// access to the flags. The flags are not user settable.
51 CompressedFlag = 1, ///< Member is a normal compressed file
52 ForeignSymbolTableFlag = 2, ///< Member is a foreign symbol table
53 LLVMSymbolTableFlag = 4, ///< Member is an LLVM symbol table
54 BytecodeFlag = 8, ///< Member is uncompressed bytecode
55 CompressedBytecodeFlag = 16, ///< Member is compressed bytecode
56 HasPathFlag = 32, ///< Member has a full or partial path
57 HasLongFilenameFlag = 64, ///< Member uses the long filename syntax
58 StringTableFlag = 256, ///< Member is an ar(1) format string table
65 /// @returns the parent Archive instance
66 /// @brief Get the archive associated with this member
67 Archive* getArchive() const { return parent; }
69 /// @returns the path to the Archive's file
70 /// @brief Get the path to the archive member
71 const sys::Path& getPath() const { return path; }
73 /// The "user" is the owner of the file per Unix security. This may not
74 /// have any applicability on non-Unix systems but is a required component
75 /// of the "ar" file format.
76 /// @brief Get the user associated with this archive member.
77 unsigned getUser() const { return info.user; }
79 /// The "group" is the owning group of the file per Unix security. This
80 /// may not have any applicability on non-Unix systems but is a required
81 /// component of the "ar" file format.
82 /// @brief Get the group associated with this archive member.
83 unsigned getGroup() const { return info.group; }
85 /// The "mode" specifies the access permissions for the file per Unix
86 /// security. This may not have any applicabiity on non-Unix systems but is
87 /// a required component of the "ar" file format.
88 /// @brief Get the permission mode associated with this archive member.
89 unsigned getMode() const { return info.mode; }
91 /// This method returns the time at which the archive member was last
92 /// modified when it was not in the archive.
93 /// @brief Get the time of last modification of the archive member.
94 sys::TimeValue getModTime() const { return info.modTime; }
96 /// @returns the size of the archive member in bytes.
97 /// @brief Get the size of the archive member.
98 unsigned getSize() const { return info.fileSize; }
100 /// This method returns the total size of the archive member as it
101 /// appears on disk. This includes the file content, the header, the
102 /// long file name if any, and the padding.
103 /// @brief Get total on-disk member size.
104 unsigned getMemberSize() const;
106 /// This method will return a pointer to the in-memory content of the
107 /// archive member, if it is available. If the data has not been loaded
108 /// into memory, the return value will be null.
109 /// @returns a pointer to the member's data.
110 /// @brief Get the data content of the archive member
111 const void* getData() const { return data; }
113 /// This method determines if the member is a regular compressed file. Note
114 /// that compressed bytecode files will yield "false" for this method.
115 /// @see isCompressedBytecode()
116 /// @returns true iff the archive member is a compressed regular file.
117 /// @brief Determine if the member is a compressed regular file.
118 bool isCompressed() const { return flags&CompressedFlag; }
120 /// @returns true iff the member is a foreign (non-LLVM) symbol table
121 /// @brief Determine if this member is a foreign symbol table.
122 bool isForeignSymbolTable() const { return flags&ForeignSymbolTableFlag; }
124 /// @returns true iff the archive member is the LLVM symbol table
125 /// @brief Determine if this member is the LLVM symbol table.
126 bool isLLVMSymbolTable() const { return flags&LLVMSymbolTableFlag; }
128 /// @returns true iff the archive member is the ar(1) string table
129 /// @brief Determine if this member is the ar(1) string table.
130 bool isStringTable() const { return flags&StringTableFlag; }
132 /// @returns true iff the archive member is an uncompressed bytecode file.
133 /// @brief Determine if this member is a bytecode file.
134 bool isBytecode() const { return flags&BytecodeFlag; }
136 /// @returns true iff the archive member is a compressed bytecode file.
137 /// @brief Determine if the member is a compressed bytecode file.
138 bool isCompressedBytecode() const { return flags&CompressedBytecodeFlag;}
140 /// @returns true iff the file name contains a path (directory) component.
141 /// @brief Determine if the member has a path
142 bool hasPath() const { return flags&HasPathFlag; }
144 /// Long filenames are an artifact of the ar(1) file format which allows
145 /// up to sixteen characters in its header and doesn't allow a path
146 /// separator character (/). To avoid this, a "long format" member name is
147 /// allowed that doesn't have this restriction. This method determines if
148 /// that "long format" is used for this member.
149 /// @returns true iff the file name uses the long form
150 /// @brief Determin if the member has a long file name
151 bool hasLongFilename() const { return flags&HasLongFilenameFlag; }
153 /// This method returns the status info (like Unix stat(2)) for the archive
154 /// member. The status info provides the file's size, permissions, and
155 /// modification time. The contents of the Path::StatusInfo structure, other
156 /// than the size and modification time, may not have utility on non-Unix
158 /// @returns the status info for the archive member
159 /// @brief Obtain the status info for the archive member
160 const sys::Path::StatusInfo& getStatusInfo() const { return info; }
162 /// This method causes the archive member to be replaced with the contents
163 /// of the file specified by \p File. The contents of \p this will be
164 /// updated to reflect the new data from \p File. The \p File must exist and
165 /// be readable on entry to this method.
166 /// @brief Replace contents of archive member with a new file.
167 void replaceWith(const sys::Path& aFile);
170 /// @name ilist methods - do not use
173 const ArchiveMember *getNext() const { return next; }
174 const ArchiveMember *getPrev() const { return prev; }
175 ArchiveMember *getNext() { return next; }
176 ArchiveMember *getPrev() { return prev; }
177 void setPrev(ArchiveMember* p) { prev = p; }
178 void setNext(ArchiveMember* n) { next = n; }
184 ArchiveMember* next; ///< Pointer to next archive member
185 ArchiveMember* prev; ///< Pointer to previous archive member
186 Archive* parent; ///< Pointer to parent archive
187 sys::Path path; ///< Path of file containing the member
188 sys::Path::StatusInfo info; ///< Status info (size,mode,date)
189 unsigned flags; ///< Flags about the archive member
190 const void* data; ///< Data for the member
193 /// @name Constructors
196 /// The default constructor is only used by the Archive's iplist when it
197 /// constructs the list's sentry node.
201 /// Used internally by the Archive class to construct an ArchiveMember.
202 /// The contents of the ArchiveMember are filled out by the Archive class.
203 ArchiveMember( Archive* PAR );
205 // So Archive can construct an ArchiveMember
206 friend class llvm::Archive;
210 /// This class defines the interface to LLVM Archive files. The Archive class
211 /// presents the archive file as an ilist of ArchiveMember objects. The members
212 /// can be rearranged in any fashion either by directly editing the ilist or by
213 /// using editing methods on the Archive class (recommended). The Archive
214 /// class also provides several ways of accessing the archive file for various
215 /// purposes such as editing and linking. Full symbol table support is provided
216 /// for loading only those files that resolve symbols. Note that read
217 /// performance of this library is _crucial_ for performance of JIT type
218 /// applications and the linkers. Consequently, the implementation of the class
219 /// is optimized for reading.
225 /// This is the ilist type over which users may iterate to examine
226 /// the contents of the archive
227 /// @brief The ilist type of ArchiveMembers that Archive contains.
228 typedef iplist<ArchiveMember> MembersList;
230 /// @brief Forward mutable iterator over ArchiveMember
231 typedef MembersList::iterator iterator;
233 /// @brief Forward immutable iterator over ArchiveMember
234 typedef MembersList::const_iterator const_iterator;
236 /// @brief Reverse mutable iterator over ArchiveMember
237 typedef std::reverse_iterator<iterator> reverse_iterator;
239 /// @brief Reverse immutable iterator over ArchiveMember
240 typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
242 /// @brief The in-memory version of the symbol table
243 typedef std::map<std::string,unsigned> SymTabType;
246 /// @name ilist interface methods
249 inline iterator begin() { return members.begin(); }
250 inline const_iterator begin() const { return members.begin(); }
251 inline iterator end () { return members.end(); }
252 inline const_iterator end () const { return members.end(); }
254 inline reverse_iterator rbegin() { return members.rbegin(); }
255 inline const_reverse_iterator rbegin() const { return members.rbegin(); }
256 inline reverse_iterator rend () { return members.rend(); }
257 inline const_reverse_iterator rend () const { return members.rend(); }
259 inline unsigned size() const { return members.size(); }
260 inline bool empty() const { return members.empty(); }
261 inline const ArchiveMember& front() const { return members.front(); }
262 inline ArchiveMember& front() { return members.front(); }
263 inline const ArchiveMember& back() const { return members.back(); }
264 inline ArchiveMember& back() { return members.back(); }
267 /// @name Constructors
270 /// Create an empty archive file and associate it with the \p Filename. This
271 /// method does not actually create the archive disk file. It creates an
272 /// empty Archive object. If the writeToDisk method is called, the archive
273 /// file \p Filename will be created at that point, with whatever content
274 /// the returned Archive object has at that time.
275 /// @returns An Archive* that represents the new archive file.
276 /// @brief Create an empty Archive.
277 static Archive* CreateEmpty(
278 const sys::Path& Filename ///< Name of the archive to (eventually) create.
281 /// Open an existing archive and load its contents in preparation for
282 /// editing. After this call, the member ilist is completely populated based
283 /// on the contents of the archive file. You should use this form of open if
284 /// you intend to modify the archive or traverse its contents (e.g. for
286 /// @brief Open and load an archive file
287 static Archive* OpenAndLoad(const sys::Path& filePath);
289 /// This method opens an existing archive file from \p Filename and reads in
290 /// its symbol table without reading in any of the archive's members. This
291 /// reduces both I/O and cpu time in opening the archive if it is to be used
292 /// solely for symbol lookup (e.g. during linking). The \p Filename must
293 /// exist and be an archive file or an exception will be thrown. This form
294 /// of opening the archive is intended for read-only operations that need to
295 /// locate members via the symbol table for link editing. Since the archve
296 /// members are not read by this method, the archive will appear empty upon
297 /// return. If editing operations are performed on the archive, they will
298 /// completely replace the contents of the archive! It is recommended that
299 /// if this form of opening the archive is used that only the symbol table
300 /// lookup methods (getSymbolTable, findModuleDefiningSymbol, and
301 /// findModulesDefiningSymbols) be used.
302 /// @throws std::string if an error occurs opening the file
303 /// @returns an Archive* that represents the archive file.
304 /// @brief Open an existing archive and load its symbols.
305 static Archive* OpenAndLoadSymbols(
306 const sys::Path& Filename ///< Name of the archive file to open
309 /// This destructor cleans up the Archive object, releases all memory, and
310 /// closes files. It does nothing with the archive file on disk. If you
311 /// haven't used the writeToDisk method by the time the destructor is
312 /// called, all changes to the archive will be lost.
313 /// @throws std::string if an error occurs
314 /// @brief Destruct in-memory archive
321 /// @returns the path to the archive file.
322 /// @brief Get the archive path.
323 const sys::Path& getPath() { return archPath; }
325 /// This method is provided so that editing methods can be invoked directly
326 /// on the Archive's iplist of ArchiveMember. However, it is recommended
327 /// that the usual STL style iterator interface be used instead.
328 /// @returns the iplist of ArchiveMember
329 /// @brief Get the iplist of the members
330 MembersList& getMembers() { return members; }
332 /// This method allows direct query of the Archive's symbol table. The
333 /// symbol table is a std::map of std::string (the symbol) to unsigned (the
334 /// file offset). Note that for efficiency reasons, the offset stored in
335 /// the symbol table is not the actual offset. It is the offset from the
336 /// beginning of the first "real" file member (after the symbol table). Use
337 /// the getFirstFileOffset() to obtain that offset and add this value to the
338 /// offset in the symbol table to obtain the real file offset. Note that
339 /// there is purposefully no interface provided by Archive to look up
340 /// members by their offset. Use the findModulesDefiningSymbols and
341 /// findModuleDefiningSymbol methods instead.
342 /// @returns the Archive's symbol table.
343 /// @brief Get the archive's symbol table
344 const SymTabType& getSymbolTable() { return symTab; }
346 /// This method returns the offset in the archive file to the first "real"
347 /// file member. Archive files, on disk, have a signature and might have a
348 /// symbol table that precedes the first actual file member. This method
349 /// allows you to determine what the size of those fields are.
350 /// @returns the offset to the first "real" file member in the archive.
351 /// @brief Get the offset to the first "real" file member in the archive.
352 unsigned getFirstFileOffset() { return firstFileOffset; }
354 /// This method will scan the archive for bytecode modules, interpret them
355 /// and return a vector of the instantiated modules in \p Modules. If an
356 /// error occurs, this method will return true. If \p ErrMessage is not null
357 /// and an error occurs, \p *ErrMessage will be set to a string explaining
358 /// the error that occurred.
359 /// @returns true if an error occurred
360 /// @brief Instantiate all the bytecode modules located in the archive
361 bool getAllModules(std::vector<Module*>& Modules, std::string* ErrMessage);
363 /// This accessor looks up the \p symbol in the archive's symbol table and
364 /// returns the associated module that defines that symbol. This method can
365 /// be called as many times as necessary. This is handy for linking the
366 /// archive into another module based on unresolved symbols. Note that the
367 /// ModuleProvider returned by this accessor should not be deleted by the
368 /// caller. It is managed internally by the Archive class. It is possible
369 /// that multiple calls to this accessor will return the same ModuleProvider
370 /// instance because the associated module defines multiple symbols.
371 /// @returns The ModuleProvider* found or null if the archive does not
372 /// contain a module that defines the \p symbol.
373 /// @brief Look up a module by symbol name.
374 ModuleProvider* findModuleDefiningSymbol(
375 const std::string& symbol ///< Symbol to be sought
378 /// This method is similar to findModuleDefiningSymbol but allows lookup of
379 /// more than one symbol at a time. If \p symbols contains a list of
380 /// undefined symbols in some module, then calling this method is like
381 /// making one complete pass through the archive to resolve symbols but is
382 /// more efficient than looking at the individual members.
383 /// @brief Look up multiple symbols in the archive.
384 void findModulesDefiningSymbols(
385 const std::set<std::string>& symbols, ///< Symbols to be sought
386 std::set<ModuleProvider*>& modules ///< The modules matching \p symbols
393 /// This method is the only way to get the archive written to disk. It
394 /// creates or overwrites the file specified when \p this was created
395 /// or opened. The arguments provide options for writing the archive. If
396 /// \p CreateSymbolTable is true, the archive is scanned for bytecode files
397 /// and a symbol table of the externally visible function and global
398 /// variable names is created. If \p TruncateNames is true, the names of the
399 /// archive members will have their path component stripped and the file
400 /// name will be truncated at 15 characters. If \p Compress is specified,
401 /// all archive members will be compressed before being written. If
402 /// \p PrintSymTab is true, the symbol table will be printed to std::cout.
403 /// @throws std::string if an error occurs
404 /// @brief Write (possibly modified) archive contents to disk
406 bool CreateSymbolTable=false, ///< Create Symbol table
407 bool TruncateNames=false, ///< Truncate the filename to 15 chars
408 bool Compress=false, ///< Compress files
409 bool PrintSymTab=false ///< Dump symtab to std::out if created
412 /// This method adds a new file to the archive. The \p filename is examined
413 /// to determine just enough information to create an ArchiveMember object
414 /// which is then inserted into the Archive object's ilist at the location
415 /// given by \p where.
416 /// @throws std::string if an error occurs reading the \p filename.
418 /// @brief Add a file to the archive.
419 void addFileBefore(const sys::Path& filename, iterator where);
421 /// This method moves a \p target member to a new location in the archive,
422 /// just before the member given by \p iterator. When the archive is
423 /// written, \p target will be written in its new location.
424 /// @brief Move a member to a new location
425 void moveMemberBefore(iterator target, iterator where);
427 /// This method removes a \p target member from the archive. When the
428 /// archive is written, it will no longer contain \p target. The associated
429 /// ArchiveMember is deleted.
430 /// @brief Remove a member.
431 void remove(iterator target);
434 /// @name Implementation
437 /// @brief Construct an Archive for \p filename and optionally map it
439 Archive(const sys::Path& filename, bool map = false );
441 /// @brief Parse the symbol table at \p data.
442 void parseSymbolTable(const void* data,unsigned len);
444 /// @brief Parse the header of a member starting at \p At
445 ArchiveMember* parseMemberHeader(const char*&At,const char*End);
447 /// @brief Check that the archive signature is correct
448 void checkSignature();
450 /// @brief Load the entire archive.
453 /// @brief Load just the symbol table.
454 void loadSymbolTable();
456 /// @brief Write the symbol table to an ofstream.
457 void writeSymbolTable(std::ofstream& ARFile,bool PrintSymTab);
459 /// @brief Write one ArchiveMember to an ofstream.
460 void writeMember(const ArchiveMember& member, std::ofstream& ARFile,
461 bool CreateSymbolTable, bool TruncateNames, bool ShouldCompress);
463 /// @brief Fill in an ArchiveMemberHeader from ArchiveMember.
464 bool fillHeader(const ArchiveMember&mbr,
465 ArchiveMemberHeader& hdr,int sz, bool TruncateNames) const;
467 /// This type is used to keep track of bytecode modules loaded from the
468 /// symbol table. It maps the file offset to a pair that consists of the
469 /// associated ArchiveMember and the ModuleProvider.
470 /// @brief Module mapping type
471 typedef std::map<unsigned,std::pair<ModuleProvider*,ArchiveMember*> >
478 sys::Path archPath; ///< Path to the archive file we read/write
479 MembersList members; ///< The ilist of ArchiveMember
480 sys::MappedFile* mapfile; ///< Raw Archive contents mapped into memory
481 const char* base; ///< Base of the memory mapped file data
482 SymTabType symTab; ///< The symbol table
483 std::string strtab; ///< The string table for long file names
484 unsigned symTabSize; ///< Size in bytes of symbol table
485 unsigned firstFileOffset; ///< Offset to first normal file.
486 ModuleMap modules; ///< The modules loaded via symbol lookup.
492 Archive(); ///< Do not implement
493 Archive(const Archive&); ///< Do not implement
494 Archive& operator=(const Archive&); ///< Do not implement
498 } // End llvm namespace