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