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