1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef BASE_FILES_FILE_H_
6 #define BASE_FILES_FILE_H_
7 
8 #include <stdint.h>
9 
10 #include <string>
11 
12 #include "base/base_export.h"
13 #include "base/files/file_path.h"
14 #include "base/files/file_tracing.h"
15 #include "base/files/platform_file.h"
16 #include "base/files/scoped_file.h"
17 #include "base/macros.h"
18 #include "base/time/time.h"
19 #include "build/build_config.h"
20 
21 #if defined(OS_POSIX) || defined(OS_FUCHSIA)
22 #include <sys/stat.h>
23 #endif
24 
25 namespace base {
26 
27 #if defined(OS_BSD) || defined(OS_MACOSX) || defined(OS_NACL) || \
28   defined(OS_FUCHSIA) || (defined(OS_ANDROID) && __ANDROID_API__ < 21)
29 typedef struct stat stat_wrapper_t;
30 #elif defined(OS_POSIX)
31 typedef struct stat64 stat_wrapper_t;
32 #endif
33 
34 // Thin wrapper around an OS-level file.
35 // Note that this class does not provide any support for asynchronous IO, other
36 // than the ability to create asynchronous handles on Windows.
37 //
38 // Note about const: this class does not attempt to determine if the underlying
39 // file system object is affected by a particular method in order to consider
40 // that method const or not. Only methods that deal with member variables in an
41 // obvious non-modifying way are marked as const. Any method that forward calls
42 // to the OS is not considered const, even if there is no apparent change to
43 // member variables.
44 class BASE_EXPORT File {
45  public:
46   // FLAG_(OPEN|CREATE).* are mutually exclusive. You should specify exactly one
47   // of the five (possibly combining with other flags) when opening or creating
48   // a file.
49   // FLAG_(WRITE|APPEND) are mutually exclusive. This is so that APPEND behavior
50   // will be consistent with O_APPEND on POSIX.
51   // FLAG_EXCLUSIVE_(READ|WRITE) only grant exclusive access to the file on
52   // creation on POSIX; for existing files, consider using Lock().
53   enum Flags {
54     FLAG_OPEN = 1 << 0,            // Opens a file, only if it exists.
55     FLAG_CREATE = 1 << 1,          // Creates a new file, only if it does not
56                                    // already exist.
57     FLAG_OPEN_ALWAYS = 1 << 2,     // May create a new file.
58     FLAG_CREATE_ALWAYS = 1 << 3,   // May overwrite an old file.
59     FLAG_OPEN_TRUNCATED = 1 << 4,  // Opens a file and truncates it, only if it
60                                    // exists.
61     FLAG_READ = 1 << 5,
62     FLAG_WRITE = 1 << 6,
63     FLAG_APPEND = 1 << 7,
64     FLAG_EXCLUSIVE_READ = 1 << 8,  // EXCLUSIVE is opposite of Windows SHARE.
65     FLAG_EXCLUSIVE_WRITE = 1 << 9,
66     FLAG_ASYNC = 1 << 10,
67     FLAG_TEMPORARY = 1 << 11,  // Used on Windows only.
68     FLAG_HIDDEN = 1 << 12,     // Used on Windows only.
69     FLAG_DELETE_ON_CLOSE = 1 << 13,
70     FLAG_WRITE_ATTRIBUTES = 1 << 14,     // Used on Windows only.
71     FLAG_SHARE_DELETE = 1 << 15,         // Used on Windows only.
72     FLAG_TERMINAL_DEVICE = 1 << 16,      // Serial port flags.
73     FLAG_BACKUP_SEMANTICS = 1 << 17,     // Used on Windows only.
74     FLAG_EXECUTE = 1 << 18,              // Used on Windows only.
75     FLAG_SEQUENTIAL_SCAN = 1 << 19,      // Used on Windows only.
76     FLAG_CAN_DELETE_ON_CLOSE = 1 << 20,  // Requests permission to delete a file
77                                          // via DeleteOnClose() (Windows only).
78                                          // See DeleteOnClose() for details.
79   };
80 
81   // This enum has been recorded in multiple histograms using PlatformFileError
82   // enum. If the order of the fields needs to change, please ensure that those
83   // histograms are obsolete or have been moved to a different enum.
84   //
85   // FILE_ERROR_ACCESS_DENIED is returned when a call fails because of a
86   // filesystem restriction. FILE_ERROR_SECURITY is returned when a browser
87   // policy doesn't allow the operation to be executed.
88   enum Error {
89     FILE_OK = 0,
90     FILE_ERROR_FAILED = -1,
91     FILE_ERROR_IN_USE = -2,
92     FILE_ERROR_EXISTS = -3,
93     FILE_ERROR_NOT_FOUND = -4,
94     FILE_ERROR_ACCESS_DENIED = -5,
95     FILE_ERROR_TOO_MANY_OPENED = -6,
96     FILE_ERROR_NO_MEMORY = -7,
97     FILE_ERROR_NO_SPACE = -8,
98     FILE_ERROR_NOT_A_DIRECTORY = -9,
99     FILE_ERROR_INVALID_OPERATION = -10,
100     FILE_ERROR_SECURITY = -11,
101     FILE_ERROR_ABORT = -12,
102     FILE_ERROR_NOT_A_FILE = -13,
103     FILE_ERROR_NOT_EMPTY = -14,
104     FILE_ERROR_INVALID_URL = -15,
105     FILE_ERROR_IO = -16,
106     // Put new entries here and increment FILE_ERROR_MAX.
107     FILE_ERROR_MAX = -17
108   };
109 
110   // This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux.
111   enum Whence {
112     FROM_BEGIN   = 0,
113     FROM_CURRENT = 1,
114     FROM_END     = 2
115   };
116 
117   // Used to hold information about a given file.
118   // If you add more fields to this structure (platform-specific fields are OK),
119   // make sure to update all functions that use it in file_util_{win|posix}.cc,
120   // too, and the ParamTraits<base::File::Info> implementation in
121   // ipc/ipc_message_utils.cc.
122   struct BASE_EXPORT Info {
123     Info();
124     ~Info();
125 #if defined(OS_POSIX) || defined(OS_FUCHSIA)
126     // Fills this struct with values from |stat_info|.
127     void FromStat(const stat_wrapper_t& stat_info);
128 #endif
129 
130     // The size of the file in bytes.  Undefined when is_directory is true.
131     int64_t size;
132 
133     // True if the file corresponds to a directory.
134     bool is_directory;
135 
136     // True if the file corresponds to a symbolic link.  For Windows currently
137     // not supported and thus always false.
138     bool is_symbolic_link;
139 
140     // The last modified time of a file.
141     Time last_modified;
142 
143     // The last accessed time of a file.
144     Time last_accessed;
145 
146     // The creation time of a file.
147     Time creation_time;
148   };
149 
150   File();
151 
152   // Creates or opens the given file. This will fail with 'access denied' if the
153   // |path| contains path traversal ('..') components.
154   File(const FilePath& path, uint32_t flags);
155 
156   // Takes ownership of |platform_file| and sets async to false.
157   explicit File(PlatformFile platform_file);
158 
159   // Takes ownership of |platform_file| and sets async to the given value.
160   // This constructor exists because on Windows you can't check if platform_file
161   // is async or not.
162   File(PlatformFile platform_file, bool async);
163 
164   // Creates an object with a specific error_details code.
165   explicit File(Error error_details);
166 
167   File(File&& other);
168 
169   ~File();
170 
171   File& operator=(File&& other);
172 
173   // Creates or opens the given file.
174   void Initialize(const FilePath& path, uint32_t flags);
175 
176   // Returns |true| if the handle / fd wrapped by this object is valid.  This
177   // method doesn't interact with the file system (and is safe to be called from
178   // ThreadRestrictions::SetIOAllowed(false) threads).
179   bool IsValid() const;
180 
181   // Returns true if a new file was created (or an old one truncated to zero
182   // length to simulate a new file, which can happen with
183   // FLAG_CREATE_ALWAYS), and false otherwise.
created()184   bool created() const { return created_; }
185 
186   // Returns the OS result of opening this file. Note that the way to verify
187   // the success of the operation is to use IsValid(), not this method:
188   //   File file(path, flags);
189   //   if (!file.IsValid())
190   //     return;
error_details()191   Error error_details() const { return error_details_; }
192 
193   PlatformFile GetPlatformFile() const;
194   PlatformFile TakePlatformFile();
195 
196   // Destroying this object closes the file automatically.
197   void Close();
198 
199   // Changes current position in the file to an |offset| relative to an origin
200   // defined by |whence|. Returns the resultant current position in the file
201   // (relative to the start) or -1 in case of error.
202   int64_t Seek(Whence whence, int64_t offset);
203 
204   // Reads the given number of bytes (or until EOF is reached) starting with the
205   // given offset. Returns the number of bytes read, or -1 on error. Note that
206   // this function makes a best effort to read all data on all platforms, so it
207   // is not intended for stream oriented files but instead for cases when the
208   // normal expectation is that actually |size| bytes are read unless there is
209   // an error.
210   int Read(int64_t offset, char* data, int size);
211 
212   // Same as above but without seek.
213   int ReadAtCurrentPos(char* data, int size);
214 
215   // Reads the given number of bytes (or until EOF is reached) starting with the
216   // given offset, but does not make any effort to read all data on all
217   // platforms. Returns the number of bytes read, or -1 on error.
218   int ReadNoBestEffort(int64_t offset, char* data, int size);
219 
220   // Same as above but without seek.
221   int ReadAtCurrentPosNoBestEffort(char* data, int size);
222 
223   // Writes the given buffer into the file at the given offset, overwritting any
224   // data that was previously there. Returns the number of bytes written, or -1
225   // on error. Note that this function makes a best effort to write all data on
226   // all platforms. |data| can be nullptr when |size| is 0.
227   // Ignores the offset and writes to the end of the file if the file was opened
228   // with FLAG_APPEND.
229   int Write(int64_t offset, const char* data, int size);
230 
231   // Save as above but without seek.
232   int WriteAtCurrentPos(const char* data, int size);
233 
234   // Save as above but does not make any effort to write all data on all
235   // platforms. Returns the number of bytes written, or -1 on error.
236   int WriteAtCurrentPosNoBestEffort(const char* data, int size);
237 
238   // Returns the current size of this file, or a negative number on failure.
239   int64_t GetLength();
240 
241   // Truncates the file to the given length. If |length| is greater than the
242   // current size of the file, the file is extended with zeros. If the file
243   // doesn't exist, |false| is returned.
244   bool SetLength(int64_t length);
245 
246   // Instructs the filesystem to flush the file to disk. (POSIX: fsync, Windows:
247   // FlushFileBuffers).
248   // Calling Flush() does not guarantee file integrity and thus is not a valid
249   // substitute for file integrity checks and recovery codepaths for malformed
250   // files. It can also be *really* slow, so avoid blocking on Flush(),
251   // especially please don't block shutdown on Flush().
252   // Latency percentiles of Flush() across all platforms as of July 2016:
253   // 50 %     > 5 ms
254   // 10 %     > 58 ms
255   //  1 %     > 357 ms
256   //  0.1 %   > 1.8 seconds
257   //  0.01 %  > 7.6 seconds
258   bool Flush();
259 
260   // Updates the file times.
261   bool SetTimes(Time last_access_time, Time last_modified_time);
262 
263   // Returns some basic information for the given file.
264   bool GetInfo(Info* info);
265 
266 #if !defined(OS_FUCHSIA)  // Fuchsia's POSIX API does not support file locking.
267 
268   // Attempts to take an exclusive write lock on the file. Returns immediately
269   // (i.e. does not wait for another process to unlock the file). If the lock
270   // was obtained, the result will be FILE_OK. A lock only guarantees
271   // that other processes may not also take a lock on the same file with the
272   // same API - it may still be opened, renamed, unlinked, etc.
273   //
274   // Common semantics:
275   //  * Locks are held by processes, but not inherited by child processes.
276   //  * Locks are released by the OS on file close or process termination.
277   //  * Locks are reliable only on local filesystems.
278   //  * Duplicated file handles may also write to locked files.
279   // Windows-specific semantics:
280   //  * Locks are mandatory for read/write APIs, advisory for mapping APIs.
281   //  * Within a process, locking the same file (by the same or new handle)
282   //    will fail.
283   // POSIX-specific semantics:
284   //  * Locks are advisory only.
285   //  * Within a process, locking the same file (by the same or new handle)
286   //    will succeed.
287   //  * Closing any descriptor on a given file releases the lock.
288   Error Lock();
289 
290   // Unlock a file previously locked.
291   Error Unlock();
292 
293 #endif  // !defined(OS_FUCHSIA)
294 
295   // Returns a new object referencing this file for use within the current
296   // process. Handling of FLAG_DELETE_ON_CLOSE varies by OS. On POSIX, the File
297   // object that was created or initialized with this flag will have unlinked
298   // the underlying file when it was created or opened. On Windows, the
299   // underlying file is deleted when the last handle to it is closed.
300   File Duplicate() const;
301 
async()302   bool async() const { return async_; }
303 
304 #if defined(OS_WIN)
305   // Sets or clears the DeleteFile disposition on the file. Returns true if
306   // the disposition was set or cleared, as indicated by |delete_on_close|.
307   //
308   // Microsoft Windows deletes a file only when the DeleteFile disposition is
309   // set on a file when the last handle to the last underlying kernel File
310   // object is closed. This disposition is be set by:
311   // - Calling the Win32 DeleteFile function with the path to a file.
312   // - Opening/creating a file with FLAG_DELETE_ON_CLOSE and then closing all
313   //   handles to that File object.
314   // - Opening/creating a file with FLAG_CAN_DELETE_ON_CLOSE and subsequently
315   //   calling DeleteOnClose(true).
316   //
317   // In all cases, all pre-existing handles to the file must have been opened
318   // with FLAG_SHARE_DELETE. Once the disposition has been set by any of the
319   // above means, no new File objects can be created for the file.
320   //
321   // So:
322   // - Use FLAG_SHARE_DELETE when creating/opening a file to allow another
323   //   entity on the system to cause it to be deleted when it is closed. (Note:
324   //   another entity can delete the file the moment after it is closed, so not
325   //   using this permission doesn't provide any protections.)
326   // - Use FLAG_DELETE_ON_CLOSE for any file that is to be deleted after use.
327   //   The OS will ensure it is deleted even in the face of process termination.
328   //   Note that it's possible for deletion to be cancelled via another File
329   //   object referencing the same file using DeleteOnClose(false) to clear the
330   //   DeleteFile disposition after the original File is closed.
331   // - Use FLAG_CAN_DELETE_ON_CLOSE in conjunction with DeleteOnClose() to alter
332   //   the DeleteFile disposition on an open handle. This fine-grained control
333   //   allows for marking a file for deletion during processing so that it is
334   //   deleted in the event of untimely process termination, and then clearing
335   //   this state once the file is suitable for persistence.
336   bool DeleteOnClose(bool delete_on_close);
337 #endif
338 
339 #if defined(OS_WIN)
340   static Error OSErrorToFileError(DWORD last_error);
341 #elif defined(OS_POSIX) || defined(OS_FUCHSIA)
342   static Error OSErrorToFileError(int saved_errno);
343 #endif
344 
345   // Gets the last global error (errno or GetLastError()) and converts it to the
346   // closest base::File::Error equivalent via OSErrorToFileError(). The returned
347   // value is only trustworthy immediately after another base::File method
348   // fails. base::File never resets the global error to zero.
349   static Error GetLastFileError();
350 
351   // Converts an error value to a human-readable form. Used for logging.
352   static std::string ErrorToString(Error error);
353 
354  private:
355   friend class FileTracing::ScopedTrace;
356 
357   // Creates or opens the given file. Only called if |path| has no
358   // traversal ('..') components.
359   void DoInitialize(const FilePath& path, uint32_t flags);
360 
361   void SetPlatformFile(PlatformFile file);
362 
363   ScopedPlatformFile file_;
364 
365   // A path to use for tracing purposes. Set if file tracing is enabled during
366   // |Initialize()|.
367   FilePath tracing_path_;
368 
369   // Object tied to the lifetime of |this| that enables/disables tracing.
370   FileTracing::ScopedEnabler trace_enabler_;
371 
372   Error error_details_;
373   bool created_;
374   bool async_;
375 
376   DISALLOW_COPY_AND_ASSIGN(File);
377 };
378 
379 }  // namespace base
380 
381 #endif  // BASE_FILES_FILE_H_
382