1 //===- llvm/System/MappedFile.h - MappedFile OS Concept ---------*- 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 file declares the llvm::sys::MappedFile class.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_SYSTEM_MAPPEDFILE_H
15 #define LLVM_SYSTEM_MAPPEDFILE_H
17 #include "llvm/System/Path.h"
18 #include "llvm/System/IncludeFile.h"
23 /// Forward declare a class used for holding platform specific information
25 struct MappedFileInfo;
27 /// This class provides an abstraction for a memory mapped file in the
28 /// operating system's filesystem. It provides platform independent operations
29 /// for mapping a file into memory for both read and write access. This class
30 /// does not provide facilities for finding the file or operating on paths to
31 /// files. The sys::Path class is used for that.
33 /// @brief An abstraction for memory mapped files.
39 READ_ACCESS = 0x0001, ///< Map the file for reading
40 WRITE_ACCESS = 0x0002, ///< Map the file for write access
41 EXEC_ACCESS = 0x0004, ///< Map the file for execution access
42 SHARED_MAPPING = 0x0008 ///< Map the file shared with other processes
45 /// @name Constructors
48 /// Construct a MappedFile to the \p path in the operating system's file
49 /// system with the mapping \p options provided.
50 /// @throws std::string if an error occurs
51 MappedFile() : path_(), options_(READ_ACCESS), base_(0), info_(0) {}
53 /// Destruct a MappedFile and release all memory associated with it.
54 /// @throws std::string if an error occurs
55 ~MappedFile() { if (info_) terminate(); }
61 /// This function determines if the file is currently mapped or not.
62 /// @returns true iff the file is mapped into memory, false otherwise
63 /// @brief Determine if a MappedFile is currently mapped
65 bool isMapped() const { return base_ != 0; }
67 /// This function returns a void* pointer to the base address of the file
68 /// mapping. This is the memory address of the first byte in the file.
69 /// Note that although a non-const pointer is returned, the memory might
70 /// not actually be writable, depending on the MappingOptions used when
71 /// the MappedFile was opened.
72 /// @returns The base pointer to the memory mapped file.
73 /// @brief Obtain the base pointer to the memory mapped file.
75 void* base() const { return base_; }
77 /// This function returns a char* pointer to the base address of the file
78 /// mapping. This is the memory address of the first byte in the file.
79 /// Note that although a non-const pointer is returned, the memory might
80 /// not actually be writable, depending on the MappingOptions used when
81 /// the MappedFile was opened.
82 /// @returns The base pointer to the memory mapped file as a char pointer.
83 /// @brief Obtain the base pointer to the memory mapped file.
85 char* charBase() const { return reinterpret_cast<char*>(base_); }
87 /// This function returns a reference to the sys::Path object kept by the
88 /// MappedFile object. This contains the path to the file that is or
90 /// @returns sys::Path containing the path name.
91 /// @brief Returns the mapped file's path as a sys::Path
93 const sys::Path& path() const { return path_; }
95 /// This function returns the number of bytes in the file.
96 /// @throws std::string if an error occurs
103 /// Open a file to be mapped and get its size but don't map it yet.
104 /// @returns true if an error occurred
106 const sys::Path& p, ///< Path to file to be mapped
107 int options = READ_ACCESS, ///< Access mode for the mapping
108 std::string* ErrMsg = 0 ///< Optional error string pointer
112 return initialize(ErrMsg);
115 /// The mapped file is removed from memory. If the file was mapped for
116 /// write access, the memory contents will be automatically synchronized
117 /// with the file's disk contents.
118 /// @brief Remove the file mapping from memory.
121 /// The mapped file is put into memory.
122 /// @returns The base memory address of the mapped file or 0 if an error
124 /// @brief Map the file into memory.
126 std::string* ErrMsg = 0///< Optional error string pointer
129 /// This method causes the size of the file, and consequently the size
130 /// of the mapping to be set. This is logically the same as unmap(),
131 /// adjust size of the file, map(). Consequently, when calling this
132 /// function, the caller should not rely on previous results of the
133 /// map(), base(), or baseChar() members as they may point to invalid
134 /// areas of memory after this call.
135 /// @throws std::string if an error occurs
136 /// @brief Set the size of the file and memory mapping.
137 bool size(size_t new_size, std::string* ErrMsg = 0);
139 void close() { if (info_) terminate(); }
142 /// @name Implementation
145 /// @brief Initialize platform-specific portion
146 bool initialize(std::string* ErrMsg);
148 /// @brief Terminate platform-specific portion
155 sys::PathWithStatus path_; ///< Path to the file.
156 int options_; ///< Options used to create the mapping
157 void* base_; ///< Pointer to the base memory address
158 mutable MappedFileInfo* info_; ///< Platform specific info for the mapping
164 ///< Disallow assignment
165 MappedFile& operator = ( const MappedFile & that );
166 ///< Disallow copying
167 MappedFile(const MappedFile& that);
173 FORCE_DEFINING_FILE_TO_BE_LINKED(SystemMappedFile)