1 /*
2  * Copyright (C) 2009 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef ART_RUNTIME_BASE_UNIX_FILE_FD_FILE_H_
18 #define ART_RUNTIME_BASE_UNIX_FILE_FD_FILE_H_
19 
20 #include <fcntl.h>
21 
22 #include <string>
23 
24 #include "base/unix_file/random_access_file.h"
25 #include "base/macros.h"
26 
27 namespace unix_file {
28 
29 // If true, check whether Flush and Close are called before destruction.
30 static constexpr bool kCheckSafeUsage = true;
31 
32 // A RandomAccessFile implementation backed by a file descriptor.
33 //
34 // Not thread safe.
35 class FdFile : public RandomAccessFile {
36  public:
37   FdFile();
38   // Creates an FdFile using the given file descriptor. Takes ownership of the
39   // file descriptor. (Use DisableAutoClose to retain ownership.)
40   FdFile(int fd, bool checkUsage);
41   FdFile(int fd, const std::string& path, bool checkUsage);
42   FdFile(int fd, const std::string& path, bool checkUsage, bool read_only_mode);
43 
FdFile(const std::string & path,int flags,bool checkUsage)44   FdFile(const std::string& path, int flags, bool checkUsage)
45       : FdFile(path, flags, 0640, checkUsage) {}
46   FdFile(const std::string& path, int flags, mode_t mode, bool checkUsage);
47 
48   // Move constructor.
FdFile(FdFile && other)49   FdFile(FdFile&& other)
50       : guard_state_(other.guard_state_),
51         fd_(other.fd_),
52         file_path_(std::move(other.file_path_)),
53         auto_close_(other.auto_close_),
54         read_only_mode_(other.read_only_mode_) {
55     other.Release();  // Release the src.
56   }
57 
58   // Move assignment operator.
59   FdFile& operator=(FdFile&& other);
60 
61   // Release the file descriptor. This will make further accesses to this FdFile invalid. Disables
62   // all further state checking.
Release()63   int Release() {
64     int tmp_fd = fd_;
65     fd_ = -1;
66     guard_state_ = GuardState::kNoCheck;
67     auto_close_ = false;
68     return tmp_fd;
69   }
70 
Reset(int fd,bool check_usage)71   void Reset(int fd, bool check_usage) {
72     if (fd_ != -1 && fd_ != fd) {
73       Destroy();
74     }
75     fd_ = fd;
76     if (check_usage) {
77       guard_state_ = fd == -1 ? GuardState::kNoCheck : GuardState::kBase;
78     } else {
79       guard_state_ = GuardState::kNoCheck;
80     }
81     // Keep the auto_close_ state.
82   }
83 
84   // Destroys an FdFile, closing the file descriptor if Close hasn't already
85   // been called. (If you care about the return value of Close, call it
86   // yourself; this is meant to handle failure cases and read-only accesses.
87   // Note though that calling Close and checking its return value is still no
88   // guarantee that data actually made it to stable storage.)
89   virtual ~FdFile();
90 
91   // RandomAccessFile API.
92   int Close() OVERRIDE WARN_UNUSED;
93   int64_t Read(char* buf, int64_t byte_count, int64_t offset) const OVERRIDE WARN_UNUSED;
94   int SetLength(int64_t new_length) OVERRIDE WARN_UNUSED;
95   int64_t GetLength() const OVERRIDE;
96   int64_t Write(const char* buf, int64_t byte_count, int64_t offset) OVERRIDE WARN_UNUSED;
97   int Flush() OVERRIDE WARN_UNUSED;
98 
99   // Short for SetLength(0); Flush(); Close();
100   // If the file was opened with a path name and unlink = true, also calls Unlink() on the path.
101   // Note that it is the the caller's responsibility to avoid races.
102   bool Erase(bool unlink = false);
103 
104   // Call unlink() if the file was opened with a path, and if open() with the name shows that
105   // the file descriptor of this file is still up-to-date. This is still racy, though, and it
106   // is up to the caller to ensure correctness in a multi-process setup.
107   bool Unlink();
108 
109   // Try to Flush(), then try to Close(); If either fails, call Erase().
110   int FlushCloseOrErase() WARN_UNUSED;
111 
112   // Try to Flush and Close(). Attempts both, but returns the first error.
113   int FlushClose() WARN_UNUSED;
114 
115   // Bonus API.
116   int Fd() const;
117   bool ReadOnlyMode() const;
118   bool CheckUsage() const;
119   bool IsOpened() const;
GetPath()120   const std::string& GetPath() const {
121     return file_path_;
122   }
123   void DisableAutoClose();
124   bool ReadFully(void* buffer, size_t byte_count) WARN_UNUSED;
125   bool PreadFully(void* buffer, size_t byte_count, size_t offset) WARN_UNUSED;
126   bool WriteFully(const void* buffer, size_t byte_count) WARN_UNUSED;
127   bool PwriteFully(const void* buffer, size_t byte_count, size_t offset) WARN_UNUSED;
128 
129   // Copy data from another file.
130   bool Copy(FdFile* input_file, int64_t offset, int64_t size);
131   // Clears the file content and resets the file offset to 0.
132   // Returns true upon success, false otherwise.
133   bool ClearContent();
134   // Resets the file offset to the beginning of the file.
135   bool ResetOffset();
136 
137   // This enum is public so that we can define the << operator over it.
138   enum class GuardState {
139     kBase,           // Base, file has not been flushed or closed.
140     kFlushed,        // File has been flushed, but not closed.
141     kClosed,         // File has been flushed and closed.
142     kNoCheck         // Do not check for the current file instance.
143   };
144 
145   // WARNING: Only use this when you know what you're doing!
146   void MarkUnchecked();
147 
148  protected:
149   // If the guard state indicates checking (!=kNoCheck), go to the target state "target". Print the
150   // given warning if the current state is or exceeds warn_threshold.
151   void moveTo(GuardState target, GuardState warn_threshold, const char* warning);
152 
153   // If the guard state indicates checking (<kNoCheck), and is below the target state "target", go
154   // to "target." If the current state is higher (excluding kNoCheck) than the trg state, print the
155   // warning.
156   void moveUp(GuardState target, const char* warning);
157 
158   // Forcefully sets the state to the given one. This can overwrite kNoCheck.
resetGuard(GuardState new_state)159   void resetGuard(GuardState new_state) {
160     if (kCheckSafeUsage) {
161       guard_state_ = new_state;
162     }
163   }
164 
165   GuardState guard_state_;
166 
167   // Opens file 'file_path' using 'flags' and 'mode'.
168   bool Open(const std::string& file_path, int flags);
169   bool Open(const std::string& file_path, int flags, mode_t mode);
170 
171  private:
172   template <bool kUseOffset>
173   bool WriteFullyGeneric(const void* buffer, size_t byte_count, size_t offset);
174 
175   void Destroy();  // For ~FdFile and operator=(&&).
176 
177   int fd_;
178   std::string file_path_;
179   bool auto_close_;
180   bool read_only_mode_;
181 
182   DISALLOW_COPY_AND_ASSIGN(FdFile);
183 };
184 
185 std::ostream& operator<<(std::ostream& os, const FdFile::GuardState& kind);
186 
187 }  // namespace unix_file
188 
189 #endif  // ART_RUNTIME_BASE_UNIX_FILE_FD_FILE_H_
190