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.
5 #ifndef BASE_PLATFORM_FILE_H_
6 #define BASE_PLATFORM_FILE_H_
8 #include "build/build_config.h"
15 #include "base/base_export.h"
16 #include "base/basictypes.h"
17 #include "base/files/file_path.h"
18 #include "base/time/time.h"
22 // ***************************************************************************
23 // ***** Don't use anything from this file anymore. It is being removed!
24 // ***** Use base/files/file.h instead
25 // ***************************************************************************
27 // PLATFORM_FILE_(OPEN|CREATE).* are mutually exclusive. You should specify
28 // exactly one of the five (possibly combining with other flags) when opening
29 // or creating a file.
30 // PLATFORM_FILE_(WRITE|APPEND) are mutually exclusive. This is so that APPEND
31 // behavior will be consistent with O_APPEND on POSIX.
32 // PLATFORM_FILE_EXCLUSIVE_(READ|WRITE) only grant exclusive access to the file
33 // on creation on POSIX; for existing files, consider using LockPlatformFile().
34 enum PlatformFileFlags
{
35 PLATFORM_FILE_OPEN
= 1 << 0, // Opens a file, only if it exists.
36 PLATFORM_FILE_CREATE
= 1 << 1, // Creates a new file, only if it
37 // does not already exist.
38 PLATFORM_FILE_OPEN_ALWAYS
= 1 << 2, // May create a new file.
39 PLATFORM_FILE_CREATE_ALWAYS
= 1 << 3, // May overwrite an old file.
40 PLATFORM_FILE_OPEN_TRUNCATED
= 1 << 4, // Opens a file and truncates it,
42 PLATFORM_FILE_READ
= 1 << 5,
43 PLATFORM_FILE_WRITE
= 1 << 6,
44 PLATFORM_FILE_APPEND
= 1 << 7,
45 PLATFORM_FILE_EXCLUSIVE_READ
= 1 << 8, // EXCLUSIVE is opposite of Windows
47 PLATFORM_FILE_EXCLUSIVE_WRITE
= 1 << 9,
48 PLATFORM_FILE_ASYNC
= 1 << 10,
49 PLATFORM_FILE_TEMPORARY
= 1 << 11, // Used on Windows only
50 PLATFORM_FILE_HIDDEN
= 1 << 12, // Used on Windows only
51 PLATFORM_FILE_DELETE_ON_CLOSE
= 1 << 13,
53 PLATFORM_FILE_WRITE_ATTRIBUTES
= 1 << 14, // Used on Windows only
55 PLATFORM_FILE_SHARE_DELETE
= 1 << 15, // Used on Windows only
57 PLATFORM_FILE_TERMINAL_DEVICE
= 1 << 16, // Serial port flags
58 PLATFORM_FILE_BACKUP_SEMANTICS
= 1 << 17, // Used on Windows only
60 PLATFORM_FILE_EXECUTE
= 1 << 18, // Used on Windows only
63 // This enum has been recorded in multiple histograms. If the order of the
64 // fields needs to change, please ensure that those histograms are obsolete or
65 // have been moved to a different enum.
67 // PLATFORM_FILE_ERROR_ACCESS_DENIED is returned when a call fails because of
68 // a filesystem restriction. PLATFORM_FILE_ERROR_SECURITY is returned when a
69 // browser policy doesn't allow the operation to be executed.
70 enum PlatformFileError
{
72 PLATFORM_FILE_ERROR_FAILED
= -1,
73 PLATFORM_FILE_ERROR_IN_USE
= -2,
74 PLATFORM_FILE_ERROR_EXISTS
= -3,
75 PLATFORM_FILE_ERROR_NOT_FOUND
= -4,
76 PLATFORM_FILE_ERROR_ACCESS_DENIED
= -5,
77 PLATFORM_FILE_ERROR_TOO_MANY_OPENED
= -6,
78 PLATFORM_FILE_ERROR_NO_MEMORY
= -7,
79 PLATFORM_FILE_ERROR_NO_SPACE
= -8,
80 PLATFORM_FILE_ERROR_NOT_A_DIRECTORY
= -9,
81 PLATFORM_FILE_ERROR_INVALID_OPERATION
= -10,
82 PLATFORM_FILE_ERROR_SECURITY
= -11,
83 PLATFORM_FILE_ERROR_ABORT
= -12,
84 PLATFORM_FILE_ERROR_NOT_A_FILE
= -13,
85 PLATFORM_FILE_ERROR_NOT_EMPTY
= -14,
86 PLATFORM_FILE_ERROR_INVALID_URL
= -15,
87 PLATFORM_FILE_ERROR_IO
= -16,
88 // Put new entries here and increment PLATFORM_FILE_ERROR_MAX.
89 PLATFORM_FILE_ERROR_MAX
= -17
92 // This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux.
93 enum PlatformFileWhence
{
94 PLATFORM_FILE_FROM_BEGIN
= 0,
95 PLATFORM_FILE_FROM_CURRENT
= 1,
96 PLATFORM_FILE_FROM_END
= 2
99 // Used to hold information about a given file.
100 // If you add more fields to this structure (platform-specific fields are OK),
101 // make sure to update all functions that use it in file_util_{win|posix}.cc
102 // too, and the ParamTraits<base::PlatformFileInfo> implementation in
103 // chrome/common/common_param_traits.cc.
104 struct BASE_EXPORT PlatformFileInfo
{
108 // The size of the file in bytes. Undefined when is_directory is true.
111 // True if the file corresponds to a directory.
114 // True if the file corresponds to a symbolic link.
115 bool is_symbolic_link
;
117 // The last modified time of a file.
118 base::Time last_modified
;
120 // The last accessed time of a file.
121 base::Time last_accessed
;
123 // The creation time of a file.
124 base::Time creation_time
;
128 typedef HANDLE PlatformFile
;
129 const PlatformFile kInvalidPlatformFileValue
= INVALID_HANDLE_VALUE
;
130 BASE_EXPORT PlatformFileError
LastErrorToPlatformFileError(DWORD last_error
);
131 #elif defined(OS_POSIX)
132 typedef int PlatformFile
;
133 const PlatformFile kInvalidPlatformFileValue
= -1;
134 BASE_EXPORT PlatformFileError
ErrnoToPlatformFileError(int saved_errno
);
137 // Closes a file handle. Returns |true| on success and |false| otherwise.
138 BASE_EXPORT
bool ClosePlatformFile(PlatformFile file
);
140 // Changes current position in the file to an |offset| relative to an origin
141 // defined by |whence|. Returns the resultant current position in the file
142 // (relative to the start) or -1 in case of error.
143 BASE_EXPORT int64
SeekPlatformFile(PlatformFile file
,
144 PlatformFileWhence whence
,
147 // Reads the given number of bytes (or until EOF is reached) starting with the
148 // given offset. Returns the number of bytes read, or -1 on error. Note that
149 // this function makes a best effort to read all data on all platforms, so it is
150 // not intended for stream oriented files but instead for cases when the normal
151 // expectation is that actually |size| bytes are read unless there is an error.
152 BASE_EXPORT
int ReadPlatformFile(PlatformFile file
, int64 offset
,
153 char* data
, int size
);
155 // Same as above but without seek.
156 BASE_EXPORT
int ReadPlatformFileAtCurrentPos(PlatformFile file
,
157 char* data
, int size
);
159 // Reads the given number of bytes (or until EOF is reached) starting with the
160 // given offset, but does not make any effort to read all data on all platforms.
161 // Returns the number of bytes read, or -1 on error.
162 BASE_EXPORT
int ReadPlatformFileNoBestEffort(PlatformFile file
, int64 offset
,
163 char* data
, int size
);
165 // Same as above but without seek.
166 BASE_EXPORT
int ReadPlatformFileCurPosNoBestEffort(PlatformFile file
,
167 char* data
, int size
);
169 // Writes the given buffer into the file at the given offset, overwritting any
170 // data that was previously there. Returns the number of bytes written, or -1
171 // on error. Note that this function makes a best effort to write all data on
173 // Ignores the offset and writes to the end of the file if the file was opened
174 // with PLATFORM_FILE_APPEND.
175 BASE_EXPORT
int WritePlatformFile(PlatformFile file
, int64 offset
,
176 const char* data
, int size
);
178 // Save as above but without seek.
179 BASE_EXPORT
int WritePlatformFileAtCurrentPos(PlatformFile file
,
180 const char* data
, int size
);
182 // Save as above but does not make any effort to write all data on all
183 // platforms. Returns the number of bytes written, or -1 on error.
184 BASE_EXPORT
int WritePlatformFileCurPosNoBestEffort(PlatformFile file
,
185 const char* data
, int size
);
187 // Truncates the given file to the given length. If |length| is greater than
188 // the current size of the file, the file is extended with zeros. If the file
189 // doesn't exist, |false| is returned.
190 BASE_EXPORT
bool TruncatePlatformFile(PlatformFile file
, int64 length
);
192 // Flushes the buffers of the given file.
193 BASE_EXPORT
bool FlushPlatformFile(PlatformFile file
);
195 // Touches the given file.
196 BASE_EXPORT
bool TouchPlatformFile(PlatformFile file
,
197 const Time
& last_access_time
,
198 const Time
& last_modified_time
);
200 // Returns some information for the given file.
201 BASE_EXPORT
bool GetPlatformFileInfo(PlatformFile file
, PlatformFileInfo
* info
);
203 // Attempts to take an exclusive write lock on the file. Returns immediately
204 // (i.e. does not wait for another process to unlock the file). If the lock
205 // was obtained, the result will be PLATFORM_FILE_OK. A lock only guarantees
206 // that other processes may not also take a lock on the same file with the
207 // same API - it may still be opened, renamed, unlinked, etc.
210 // * Locks are held by processes, but not inherited by child processes.
211 // * Locks are released by the OS on file handle close or process termination.
212 // * Locks are reliable only on local filesystems.
213 // * Duplicated file handles may also write to locked files.
214 // Windows-specific semantics:
215 // * Locks are mandatory for read/write APIs, advisory for mapping APIs.
216 // * Within a process, locking the same file (by the same or new handle)
218 // POSIX-specific semantics:
219 // * Locks are advisory only.
220 // * Within a process, locking the same file (by the same or new handle)
222 // * Closing any descriptor on a given file releases the lock.
223 BASE_EXPORT PlatformFileError
LockPlatformFile(PlatformFile file
);
225 // Unlock a file previously locked with LockPlatformFile.
226 BASE_EXPORT PlatformFileError
UnlockPlatformFile(PlatformFile file
);
228 // Use this class to pass ownership of a PlatformFile to a receiver that may or
229 // may not want to accept it. This class does not own the storage for the
234 // void MaybeProcessFile(PassPlatformFile pass_file) {
236 // PlatformFile file = pass_file.ReleaseValue();
237 // // Now, we are responsible for closing |file|.
241 // void OpenAndMaybeProcessFile(const FilePath& path) {
242 // PlatformFile file = CreatePlatformFile(path, ...);
243 // MaybeProcessFile(PassPlatformFile(&file));
244 // if (file != kInvalidPlatformFileValue)
245 // ClosePlatformFile(file);
248 class BASE_EXPORT PassPlatformFile
{
250 explicit PassPlatformFile(PlatformFile
* value
) : value_(value
) {
253 // Called to retrieve the PlatformFile stored in this object. The caller
254 // gains ownership of the PlatformFile and is now responsible for closing it.
255 // Any subsequent calls to this method will return an invalid PlatformFile.
256 PlatformFile
ReleaseValue() {
257 PlatformFile temp
= *value_
;
258 *value_
= kInvalidPlatformFileValue
;
263 PlatformFile
* value_
;
268 #endif // BASE_PLATFORM_FILE_H_