1 //===-- llvm/Bitcode/Archive.h - LLVM Bitcode Archive -----------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // 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/Bitcode/Archive library. This library is used to read and write
13 // archive (*.a) files that contain LLVM bitcode files (or others).
15 //===----------------------------------------------------------------------===//
17 #ifndef TOOLS_LLVM_AR_ARCHIVE_H
18 #define TOOLS_LLVM_AR_ARCHIVE_H
20 #include "llvm/ADT/ilist.h"
21 #include "llvm/ADT/ilist_node.h"
22 #include "llvm/Support/Path.h"
23 #include "llvm/Support/PathV1.h"
30 // Forward declare classes
31 class Module; // From VMCore
32 class Archive; // Declared below
33 class ArchiveMemberHeader; // Internal implementation class
34 class LLVMContext; // Global data
36 /// This class is the main class manipulated by users of the Archive class. It
37 /// holds information about one member of the Archive. It is also the element
38 /// stored by the Archive's ilist, the Archive's main abstraction. Because of
39 /// the special requirements of archive files, users are not permitted to
40 /// construct ArchiveMember instances. You should obtain them from the methods
41 /// of the Archive class instead.
42 /// @brief This class represents a single archive member.
43 class ArchiveMember : public ilist_node<ArchiveMember> {
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 SVR4SymbolTableFlag = 1, ///< Member is a SVR4 symbol table
52 BSD4SymbolTableFlag = 2, ///< Member is a BSD4 symbol table
53 BitcodeFlag = 4, ///< Member is bitcode
54 HasPathFlag = 8, ///< Member has a full or partial path
55 HasLongFilenameFlag = 16, ///< Member uses the long filename syntax
56 StringTableFlag = 32 ///< Member is an ar(1) format string table
63 /// @returns the parent Archive instance
64 /// @brief Get the archive associated with this member
65 Archive* getArchive() const { return parent; }
67 /// @returns the path to the Archive's file
68 /// @brief Get the path to the archive member
69 const sys::Path& getPath() const { return path; }
71 /// The "user" is the owner of the file per Unix security. This may not
72 /// have any applicability on non-Unix systems but is a required component
73 /// of the "ar" file format.
74 /// @brief Get the user associated with this archive member.
75 unsigned getUser() const { return info.getUser(); }
77 /// The "group" is the owning group of the file per Unix security. This
78 /// may not have any applicability on non-Unix systems but is a required
79 /// component of the "ar" file format.
80 /// @brief Get the group associated with this archive member.
81 unsigned getGroup() const { return info.getGroup(); }
83 /// The "mode" specifies the access permissions for the file per Unix
84 /// security. This may not have any applicability on non-Unix systems but is
85 /// a required component of the "ar" file format.
86 /// @brief Get the permission mode associated with this archive member.
87 unsigned getMode() const { return info.getMode(); }
89 /// This method returns the time at which the archive member was last
90 /// modified when it was not in the archive.
91 /// @brief Get the time of last modification of the archive member.
92 sys::TimeValue getModTime() const { return info.getTimestamp(); }
94 /// @returns the size of the archive member in bytes.
95 /// @brief Get the size of the archive member.
96 uint64_t getSize() const { return info.getSize(); }
98 /// This method returns the total size of the archive member as it
99 /// appears on disk. This includes the file content, the header, the
100 /// long file name if any, and the padding.
101 /// @brief Get total on-disk member size.
102 unsigned getMemberSize() const;
104 /// This method will return a pointer to the in-memory content of the
105 /// archive member, if it is available. If the data has not been loaded
106 /// into memory, the return value will be null.
107 /// @returns a pointer to the member's data.
108 /// @brief Get the data content of the archive member
109 const char* getData() const { return data; }
111 /// @returns true iff the member is a SVR4 (non-LLVM) symbol table
112 /// @brief Determine if this member is a SVR4 symbol table.
113 bool isSVR4SymbolTable() const { return flags&SVR4SymbolTableFlag; }
115 /// @returns true iff the member is a BSD4.4 (non-LLVM) symbol table
116 /// @brief Determine if this member is a BSD4.4 symbol table.
117 bool isBSD4SymbolTable() const { return flags&BSD4SymbolTableFlag; }
119 /// @returns true iff the archive member is the ar(1) string table
120 /// @brief Determine if this member is the ar(1) string table.
121 bool isStringTable() const { return flags&StringTableFlag; }
123 /// @returns true iff the archive member is a bitcode file.
124 /// @brief Determine if this member is a bitcode file.
125 bool isBitcode() const { return flags&BitcodeFlag; }
127 /// @returns true iff the file name contains a path (directory) component.
128 /// @brief Determine if the member has a path
129 bool hasPath() const { return flags&HasPathFlag; }
131 /// Long filenames are an artifact of the ar(1) file format which allows
132 /// up to sixteen characters in its header and doesn't allow a path
133 /// separator character (/). To avoid this, a "long format" member name is
134 /// allowed that doesn't have this restriction. This method determines if
135 /// that "long format" is used for this member.
136 /// @returns true iff the file name uses the long form
137 /// @brief Determine if the member has a long file name
138 bool hasLongFilename() const { return flags&HasLongFilenameFlag; }
140 /// This method returns the status info (like Unix stat(2)) for the archive
141 /// member. The status info provides the file's size, permissions, and
142 /// modification time. The contents of the Path::StatusInfo structure, other
143 /// than the size and modification time, may not have utility on non-Unix
145 /// @returns the status info for the archive member
146 /// @brief Obtain the status info for the archive member
147 const sys::FileStatus &getFileStatus() const { return info; }
149 /// This method causes the archive member to be replaced with the contents
150 /// of the file specified by \p File. The contents of \p this will be
151 /// updated to reflect the new data from \p File. The \p File must exist and
152 /// be readable on entry to this method.
153 /// @returns true if an error occurred, false otherwise
154 /// @brief Replace contents of archive member with a new file.
155 bool replaceWith(const sys::Path &aFile, std::string* ErrMsg);
161 Archive* parent; ///< Pointer to parent archive
162 sys::PathWithStatus path; ///< Path of file containing the member
163 sys::FileStatus info; ///< Status info (size,mode,date)
164 unsigned flags; ///< Flags about the archive member
165 const char* data; ///< Data for the member
168 /// @name Constructors
171 /// The default constructor is only used by the Archive's iplist when it
172 /// constructs the list's sentry node.
176 /// Used internally by the Archive class to construct an ArchiveMember.
177 /// The contents of the ArchiveMember are filled out by the Archive class.
178 explicit ArchiveMember(Archive *PAR);
180 // So Archive can construct an ArchiveMember
181 friend class llvm::Archive;
185 /// This class defines the interface to LLVM Archive files. The Archive class
186 /// presents the archive file as an ilist of ArchiveMember objects. The members
187 /// can be rearranged in any fashion either by directly editing the ilist or by
188 /// using editing methods on the Archive class (recommended). The Archive
189 /// class also provides several ways of accessing the archive file for various
190 /// purposes such as editing and linking. Full symbol table support is provided
191 /// for loading only those files that resolve symbols. Note that read
192 /// performance of this library is _crucial_ for performance of JIT type
193 /// applications and the linkers. Consequently, the implementation of the class
194 /// is optimized for reading.
200 /// This is the ilist type over which users may iterate to examine
201 /// the contents of the archive
202 /// @brief The ilist type of ArchiveMembers that Archive contains.
203 typedef iplist<ArchiveMember> MembersList;
205 /// @brief Forward mutable iterator over ArchiveMember
206 typedef MembersList::iterator iterator;
208 /// @brief Forward immutable iterator over ArchiveMember
209 typedef MembersList::const_iterator const_iterator;
211 /// @brief Reverse mutable iterator over ArchiveMember
212 typedef std::reverse_iterator<iterator> reverse_iterator;
214 /// @brief Reverse immutable iterator over ArchiveMember
215 typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
217 /// @brief The in-memory version of the symbol table
218 typedef std::map<std::string,unsigned> SymTabType;
221 /// @name ilist accessor methods
224 inline iterator begin() { return members.begin(); }
225 inline const_iterator begin() const { return members.begin(); }
226 inline iterator end () { return members.end(); }
227 inline const_iterator end () const { return members.end(); }
229 inline reverse_iterator rbegin() { return members.rbegin(); }
230 inline const_reverse_iterator rbegin() const { return members.rbegin(); }
231 inline reverse_iterator rend () { return members.rend(); }
232 inline const_reverse_iterator rend () const { return members.rend(); }
234 inline size_t size() const { return members.size(); }
235 inline bool empty() const { return members.empty(); }
236 inline const ArchiveMember& front() const { return members.front(); }
237 inline ArchiveMember& front() { return members.front(); }
238 inline const ArchiveMember& back() const { return members.back(); }
239 inline ArchiveMember& back() { return members.back(); }
242 /// @name ilist mutator methods
245 /// This method splices a \p src member from an archive (possibly \p this),
246 /// to a position just before the member given by \p dest in \p this. When
247 /// the archive is written, \p src will be written in its new location.
248 /// @brief Move a member to a new location
249 inline void splice(iterator dest, Archive& arch, iterator src)
250 { return members.splice(dest,arch.members,src); }
252 /// This method erases a \p target member from the archive. When the
253 /// archive is written, it will no longer contain \p target. The associated
254 /// ArchiveMember is deleted.
255 /// @brief Erase a member.
256 inline iterator erase(iterator target) { return members.erase(target); }
259 /// @name Constructors
262 /// Create an empty archive file and associate it with the \p Filename. This
263 /// method does not actually create the archive disk file. It creates an
264 /// empty Archive object. If the writeToDisk method is called, the archive
265 /// file \p Filename will be created at that point, with whatever content
266 /// the returned Archive object has at that time.
267 /// @returns An Archive* that represents the new archive file.
268 /// @brief Create an empty Archive.
269 static Archive* CreateEmpty(
270 const sys::Path& Filename,///< Name of the archive to (eventually) create.
271 LLVMContext& C ///< Context to use for global information
274 /// Open an existing archive and load its contents in preparation for
275 /// editing. After this call, the member ilist is completely populated based
276 /// on the contents of the archive file. You should use this form of open if
277 /// you intend to modify the archive or traverse its contents (e.g. for
279 /// @brief Open and load an archive file
280 static Archive* OpenAndLoad(
281 const sys::Path& filePath, ///< The file path to open and load
282 LLVMContext& C, ///< The context to use for global information
283 std::string* ErrorMessage ///< An optional error string
286 /// This method opens an existing archive file from \p Filename and reads in
287 /// its symbol table without reading in any of the archive's members. This
288 /// reduces both I/O and cpu time in opening the archive if it is to be used
289 /// solely for symbol lookup (e.g. during linking). The \p Filename must
290 /// exist and be an archive file or an error will be returned. This form
291 /// of opening the archive is intended for read-only operations that need to
292 /// locate members via the symbol table for link editing. Since the archve
293 /// members are not read by this method, the archive will appear empty upon
294 /// return. If editing operations are performed on the archive, they will
295 /// completely replace the contents of the archive! It is recommended that
296 /// if this form of opening the archive is used that only the symbol table
297 /// lookup methods (getSymbolTable, findModuleDefiningSymbol, and
298 /// findModulesDefiningSymbols) be used.
299 /// @returns an Archive* that represents the archive file, or null on error.
300 /// @brief Open an existing archive and load its symbols.
301 static Archive* OpenAndLoadSymbols(
302 const sys::Path& Filename, ///< Name of the archive file to open
303 LLVMContext& C, ///< The context to use for global info
304 std::string* ErrorMessage=0 ///< An optional error string
307 /// This destructor cleans up the Archive object, releases all memory, and
308 /// closes files. It does nothing with the archive file on disk. If you
309 /// haven't used the writeToDisk method by the time the destructor is
310 /// called, all changes to the archive will be lost.
311 /// @brief Destruct in-memory archive
318 /// @returns the path to the archive file.
319 /// @brief Get the archive path.
320 const sys::Path& getPath() { return archPath; }
322 /// This method is provided so that editing methods can be invoked directly
323 /// on the Archive's iplist of ArchiveMember. However, it is recommended
324 /// that the usual STL style iterator interface be used instead.
325 /// @returns the iplist of ArchiveMember
326 /// @brief Get the iplist of the members
327 MembersList& getMembers() { return members; }
329 /// This method allows direct query of the Archive's symbol table. The
330 /// symbol table is a std::map of std::string (the symbol) to unsigned (the
331 /// file offset). Note that for efficiency reasons, the offset stored in
332 /// the symbol table is not the actual offset. It is the offset from the
333 /// beginning of the first "real" file member (after the symbol table). Use
334 /// the getFirstFileOffset() to obtain that offset and add this value to the
335 /// offset in the symbol table to obtain the real file offset. Note that
336 /// there is purposefully no interface provided by Archive to look up
337 /// members by their offset. Use the findModulesDefiningSymbols and
338 /// findModuleDefiningSymbol methods instead.
339 /// @returns the Archive's symbol table.
340 /// @brief Get the archive's symbol table
341 const SymTabType& getSymbolTable() { return symTab; }
343 /// This method returns the offset in the archive file to the first "real"
344 /// file member. Archive files, on disk, have a signature and might have a
345 /// symbol table that precedes the first actual file member. This method
346 /// allows you to determine what the size of those fields are.
347 /// @returns the offset to the first "real" file member in the archive.
348 /// @brief Get the offset to the first "real" file member in the archive.
349 unsigned getFirstFileOffset() { return firstFileOffset; }
351 /// This method will scan the archive for bitcode modules, interpret them
352 /// and return a vector of the instantiated modules in \p Modules. If an
353 /// error occurs, this method will return true. If \p ErrMessage is not null
354 /// and an error occurs, \p *ErrMessage will be set to a string explaining
355 /// the error that occurred.
356 /// @returns true if an error occurred
357 /// @brief Instantiate all the bitcode modules located in the archive
358 bool getAllModules(std::vector<Module*>& Modules, std::string* ErrMessage);
360 /// This accessor looks up the \p symbol in the archive's symbol table and
361 /// returns the associated module that defines that symbol. This method can
362 /// be called as many times as necessary. This is handy for linking the
363 /// archive into another module based on unresolved symbols. Note that the
364 /// Module returned by this accessor should not be deleted by the caller. It
365 /// is managed internally by the Archive class. It is possible that multiple
366 /// calls to this accessor will return the same Module instance because the
367 /// associated module defines multiple symbols.
368 /// @returns The Module* found or null if the archive does not contain a
369 /// module that defines the \p symbol.
370 /// @brief Look up a module by symbol name.
371 Module* findModuleDefiningSymbol(
372 const std::string& symbol, ///< Symbol to be sought
373 std::string* ErrMessage ///< Error message storage, if non-zero
376 /// This method is similar to findModuleDefiningSymbol but allows lookup of
377 /// more than one symbol at a time. If \p symbols contains a list of
378 /// undefined symbols in some module, then calling this method is like
379 /// making one complete pass through the archive to resolve symbols but is
380 /// more efficient than looking at the individual members. Note that on
381 /// exit, the symbols resolved by this method will be removed from \p
382 /// symbols to ensure they are not re-searched on a subsequent call. If
383 /// you need to retain the list of symbols, make a copy.
384 /// @brief Look up multiple symbols in the archive.
385 bool findModulesDefiningSymbols(
386 std::set<std::string>& symbols, ///< Symbols to be sought
387 SmallVectorImpl<Module*>& modules, ///< The modules matching \p symbols
388 std::string* ErrMessage ///< Error msg storage, if non-zero
391 /// This method determines whether the archive is a properly formed llvm
392 /// bitcode archive. It first makes sure the symbol table has been loaded
393 /// and has a non-zero size. If it does, then it is an archive. If not,
394 /// then it tries to load all the bitcode modules of the archive. Finally,
395 /// it returns whether it was successful.
396 /// @returns true if the archive is a proper llvm bitcode archive
397 /// @brief Determine whether the archive is a proper llvm bitcode archive.
398 bool isBitcodeArchive();
404 /// This method is the only way to get the archive written to disk. It
405 /// creates or overwrites the file specified when \p this was created
406 /// or opened. The arguments provide options for writing the archive. If
407 /// \p CreateSymbolTable is true, the archive is scanned for bitcode files
408 /// and a symbol table of the externally visible function and global
409 /// variable names is created. If \p TruncateNames is true, the names of the
410 /// archive members will have their path component stripped and the file
411 /// name will be truncated at 15 characters. If \p Compress is specified,
412 /// all archive members will be compressed before being written. If
413 /// \p PrintSymTab is true, the symbol table will be printed to std::cout.
414 /// @returns true if an error occurred, \p error set to error message;
415 /// returns false if the writing succeeded.
416 /// @brief Write (possibly modified) archive contents to disk
418 bool CreateSymbolTable=false, ///< Create Symbol table
419 bool TruncateNames=false, ///< Truncate the filename to 15 chars
420 std::string* ErrMessage=0 ///< If non-null, where error msg is set
423 /// This method adds a new file to the archive. The \p filename is examined
424 /// to determine just enough information to create an ArchiveMember object
425 /// which is then inserted into the Archive object's ilist at the location
426 /// given by \p where.
427 /// @returns true if an error occurred, false otherwise
428 /// @brief Add a file to the archive.
430 const sys::Path& filename, ///< The file to be added
431 iterator where, ///< Insertion point
432 std::string* ErrMsg ///< Optional error message location
436 /// @name Implementation
439 /// @brief Construct an Archive for \p filename and optionally map it
441 explicit Archive(const sys::Path& filename, LLVMContext& C);
443 /// @returns A fully populated ArchiveMember or 0 if an error occurred.
444 /// @brief Parse the header of a member starting at \p At
445 ArchiveMember* parseMemberHeader(
446 const char*&At, ///< The pointer to the location we're parsing
447 const char*End, ///< The pointer to the end of the archive
448 std::string* error ///< Optional error message catcher
451 /// @param ErrMessage Set to address of a std::string to get error messages
452 /// @returns false on error
453 /// @brief Check that the archive signature is correct
454 bool checkSignature(std::string* ErrMessage);
456 /// @param ErrMessage Set to address of a std::string to get error messages
457 /// @returns false on error
458 /// @brief Load the entire archive.
459 bool loadArchive(std::string* ErrMessage);
461 /// @param ErrMessage Set to address of a std::string to get error messages
462 /// @returns false on error
463 /// @brief Load just the symbol table.
464 bool loadSymbolTable(std::string* ErrMessage);
466 /// Writes one ArchiveMember to an ofstream. If an error occurs, returns
467 /// false, otherwise true. If an error occurs and error is non-null then
468 /// it will be set to an error message.
469 /// @returns false if writing member succeeded,
470 /// returns true if writing member failed, \p error set to error message.
472 const ArchiveMember& member, ///< The member to be written
473 std::ofstream& ARFile, ///< The file to write member onto
474 bool CreateSymbolTable, ///< Should symbol table be created?
475 bool TruncateNames, ///< Should names be truncated to 11 chars?
476 std::string* ErrMessage ///< If non-null, place were error msg is set
479 /// @brief Fill in an ArchiveMemberHeader from ArchiveMember.
480 bool fillHeader(const ArchiveMember&mbr,
481 ArchiveMemberHeader& hdr,int sz, bool TruncateNames) const;
483 /// @brief Maps archive into memory
484 bool mapToMemory(std::string* ErrMsg);
486 /// @brief Frees all the members and unmaps the archive file.
487 void cleanUpMemory();
489 /// This type is used to keep track of bitcode modules loaded from the
490 /// symbol table. It maps the file offset to a pair that consists of the
491 /// associated ArchiveMember and the Module.
492 /// @brief Module mapping type
493 typedef std::map<unsigned,std::pair<Module*,ArchiveMember*> >
501 sys::Path archPath; ///< Path to the archive file we read/write
502 MembersList members; ///< The ilist of ArchiveMember
503 MemoryBuffer *mapfile; ///< Raw Archive contents mapped into memory
504 const char* base; ///< Base of the memory mapped file data
505 SymTabType symTab; ///< The symbol table
506 std::string strtab; ///< The string table for long file names
507 unsigned symTabSize; ///< Size in bytes of symbol table
508 unsigned firstFileOffset; ///< Offset to first normal file.
509 ModuleMap modules; ///< The modules loaded via symbol lookup.
510 ArchiveMember* foreignST; ///< This holds the foreign symbol table.
511 LLVMContext& Context; ///< This holds global data.
516 Archive() LLVM_DELETED_FUNCTION;
517 Archive(const Archive&) LLVM_DELETED_FUNCTION;
518 Archive& operator=(const Archive&) LLVM_DELETED_FUNCTION;
522 } // End llvm namespace