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 #include <string>
22 #include "base/unix_file/random_access_file.h"
23 #include "base/macros.h"
24 
25 namespace unix_file {
26 
27 // If true, check whether Flush and Close are called before destruction.
28 static constexpr bool kCheckSafeUsage = true;
29 
30 // A RandomAccessFile implementation backed by a file descriptor.
31 //
32 // Not thread safe.
33 class FdFile : public RandomAccessFile {
34  public:
35   FdFile();
36   // Creates an FdFile using the given file descriptor. Takes ownership of the
37   // file descriptor. (Use DisableAutoClose to retain ownership.)
38   FdFile(int fd, bool checkUsage);
39   FdFile(int fd, const std::string& path, bool checkUsage);
40   FdFile(int fd, const std::string& path, bool checkUsage, bool read_only_mode);
41 
42   // Destroys an FdFile, closing the file descriptor if Close hasn't already
43   // been called. (If you care about the return value of Close, call it
44   // yourself; this is meant to handle failure cases and read-only accesses.
45   // Note though that calling Close and checking its return value is still no
46   // guarantee that data actually made it to stable storage.)
47   virtual ~FdFile();
48 
49   // Opens file 'file_path' using 'flags' and 'mode'.
50   bool Open(const std::string& file_path, int flags);
51   bool Open(const std::string& file_path, int flags, mode_t mode);
52 
53   // RandomAccessFile API.
54   int Close() OVERRIDE WARN_UNUSED;
55   int64_t Read(char* buf, int64_t byte_count, int64_t offset) const OVERRIDE WARN_UNUSED;
56   int SetLength(int64_t new_length) OVERRIDE WARN_UNUSED;
57   int64_t GetLength() const OVERRIDE;
58   int64_t Write(const char* buf, int64_t byte_count, int64_t offset) OVERRIDE WARN_UNUSED;
59   int Flush() OVERRIDE WARN_UNUSED;
60 
61   // Short for SetLength(0); Flush(); Close();
62   void Erase();
63 
64   // Try to Flush(), then try to Close(); If either fails, call Erase().
65   int FlushCloseOrErase() WARN_UNUSED;
66 
67   // Try to Flush and Close(). Attempts both, but returns the first error.
68   int FlushClose() WARN_UNUSED;
69 
70   // Bonus API.
71   int Fd() const;
72   bool ReadOnlyMode() const;
73   bool CheckUsage() const;
74   bool IsOpened() const;
GetPath()75   const std::string& GetPath() const {
76     return file_path_;
77   }
78   void DisableAutoClose();
79   bool ReadFully(void* buffer, size_t byte_count) WARN_UNUSED;
80   bool PreadFully(void* buffer, size_t byte_count, size_t offset) WARN_UNUSED;
81   bool WriteFully(const void* buffer, size_t byte_count) WARN_UNUSED;
82   bool PwriteFully(const void* buffer, size_t byte_count, size_t offset) WARN_UNUSED;
83 
84   // Copy data from another file.
85   bool Copy(FdFile* input_file, int64_t offset, int64_t size);
86   // Clears the file content and resets the file offset to 0.
87   // Returns true upon success, false otherwise.
88   bool ClearContent();
89   // Resets the file offset to the beginning of the file.
90   bool ResetOffset();
91 
92   // This enum is public so that we can define the << operator over it.
93   enum class GuardState {
94     kBase,           // Base, file has not been flushed or closed.
95     kFlushed,        // File has been flushed, but not closed.
96     kClosed,         // File has been flushed and closed.
97     kNoCheck         // Do not check for the current file instance.
98   };
99 
100   // WARNING: Only use this when you know what you're doing!
101   void MarkUnchecked();
102 
103  protected:
104   // If the guard state indicates checking (!=kNoCheck), go to the target state "target". Print the
105   // given warning if the current state is or exceeds warn_threshold.
106   void moveTo(GuardState target, GuardState warn_threshold, const char* warning);
107 
108   // If the guard state indicates checking (<kNoCheck), and is below the target state "target", go
109   // to "target." If the current state is higher (excluding kNoCheck) than the trg state, print the
110   // warning.
111   void moveUp(GuardState target, const char* warning);
112 
113   // Forcefully sets the state to the given one. This can overwrite kNoCheck.
resetGuard(GuardState new_state)114   void resetGuard(GuardState new_state) {
115     if (kCheckSafeUsage) {
116       guard_state_ = new_state;
117     }
118   }
119 
120   GuardState guard_state_;
121 
122  private:
123   template <bool kUseOffset>
124   bool WriteFullyGeneric(const void* buffer, size_t byte_count, size_t offset);
125 
126   int fd_;
127   std::string file_path_;
128   bool auto_close_;
129   bool read_only_mode_;
130 
131   DISALLOW_COPY_AND_ASSIGN(FdFile);
132 };
133 
134 std::ostream& operator<<(std::ostream& os, const FdFile::GuardState& kind);
135 
136 }  // namespace unix_file
137 
138 #endif  // ART_RUNTIME_BASE_UNIX_FILE_FD_FILE_H_
139