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 // PLATFORM_FILE_(OPEN|CREATE).* are mutually exclusive. You should specify
23 // exactly one of the five (possibly combining with other flags) when opening
24 // or creating a file.
25 // PLATFORM_FILE_(WRITE|APPEND) are mutually exclusive. This is so that APPEND
26 // behavior will be consistent with O_APPEND on POSIX.
27 enum PlatformFileFlags
{
28 PLATFORM_FILE_OPEN
= 1 << 0, // Opens a file, only if it exists.
29 PLATFORM_FILE_CREATE
= 1 << 1, // Creates a new file, only if it
30 // does not already exist.
31 PLATFORM_FILE_OPEN_ALWAYS
= 1 << 2, // May create a new file.
32 PLATFORM_FILE_CREATE_ALWAYS
= 1 << 3, // May overwrite an old file.
33 PLATFORM_FILE_OPEN_TRUNCATED
= 1 << 4, // Opens a file and truncates it,
35 PLATFORM_FILE_READ
= 1 << 5,
36 PLATFORM_FILE_WRITE
= 1 << 6,
37 PLATFORM_FILE_APPEND
= 1 << 7,
38 PLATFORM_FILE_EXCLUSIVE_READ
= 1 << 8, // EXCLUSIVE is opposite of Windows
40 PLATFORM_FILE_EXCLUSIVE_WRITE
= 1 << 9,
41 PLATFORM_FILE_ASYNC
= 1 << 10,
42 PLATFORM_FILE_TEMPORARY
= 1 << 11, // Used on Windows only
43 PLATFORM_FILE_HIDDEN
= 1 << 12, // Used on Windows only
44 PLATFORM_FILE_DELETE_ON_CLOSE
= 1 << 13,
46 PLATFORM_FILE_WRITE_ATTRIBUTES
= 1 << 14, // Used on Windows only
48 PLATFORM_FILE_SHARE_DELETE
= 1 << 15, // Used on Windows only
50 PLATFORM_FILE_TERMINAL_DEVICE
= 1 << 16, // Serial port flags
51 PLATFORM_FILE_BACKUP_SEMANTICS
= 1 << 17, // Used on Windows only
53 PLATFORM_FILE_EXECUTE
= 1 << 18, // Used on Windows only
56 // PLATFORM_FILE_ERROR_ACCESS_DENIED is returned when a call fails because of
57 // a filesystem restriction. PLATFORM_FILE_ERROR_SECURITY is returned when a
58 // browser policy doesn't allow the operation to be executed.
59 enum PlatformFileError
{
61 PLATFORM_FILE_ERROR_FAILED
= -1,
62 PLATFORM_FILE_ERROR_IN_USE
= -2,
63 PLATFORM_FILE_ERROR_EXISTS
= -3,
64 PLATFORM_FILE_ERROR_NOT_FOUND
= -4,
65 PLATFORM_FILE_ERROR_ACCESS_DENIED
= -5,
66 PLATFORM_FILE_ERROR_TOO_MANY_OPENED
= -6,
67 PLATFORM_FILE_ERROR_NO_MEMORY
= -7,
68 PLATFORM_FILE_ERROR_NO_SPACE
= -8,
69 PLATFORM_FILE_ERROR_NOT_A_DIRECTORY
= -9,
70 PLATFORM_FILE_ERROR_INVALID_OPERATION
= -10,
71 PLATFORM_FILE_ERROR_SECURITY
= -11,
72 PLATFORM_FILE_ERROR_ABORT
= -12,
73 PLATFORM_FILE_ERROR_NOT_A_FILE
= -13,
74 PLATFORM_FILE_ERROR_NOT_EMPTY
= -14,
75 PLATFORM_FILE_ERROR_INVALID_URL
= -15,
76 PLATFORM_FILE_ERROR_IO
= -16,
77 // Put new entries here and increment PLATFORM_FILE_ERROR_MAX.
78 PLATFORM_FILE_ERROR_MAX
= -17
81 // This explicit mapping matches both FILE_ on Windows and SEEK_ on Linux.
82 enum PlatformFileWhence
{
83 PLATFORM_FILE_FROM_BEGIN
= 0,
84 PLATFORM_FILE_FROM_CURRENT
= 1,
85 PLATFORM_FILE_FROM_END
= 2
88 // Used to hold information about a given file.
89 // If you add more fields to this structure (platform-specific fields are OK),
90 // make sure to update all functions that use it in file_util_{win|posix}.cc
91 // too, and the ParamTraits<base::PlatformFileInfo> implementation in
92 // chrome/common/common_param_traits.cc.
93 struct BASE_EXPORT PlatformFileInfo
{
97 // The size of the file in bytes. Undefined when is_directory is true.
100 // True if the file corresponds to a directory.
103 // True if the file corresponds to a symbolic link.
104 bool is_symbolic_link
;
106 // The last modified time of a file.
107 base::Time last_modified
;
109 // The last accessed time of a file.
110 base::Time last_accessed
;
112 // The creation time of a file.
113 base::Time creation_time
;
117 typedef HANDLE PlatformFile
;
118 const PlatformFile kInvalidPlatformFileValue
= INVALID_HANDLE_VALUE
;
119 PlatformFileError
LastErrorToPlatformFileError(DWORD saved_errno
);
120 #elif defined(OS_POSIX)
121 typedef int PlatformFile
;
122 const PlatformFile kInvalidPlatformFileValue
= -1;
123 PlatformFileError
ErrnoToPlatformFileError(int saved_errno
);
126 // Creates or opens the given file. If |created| is provided, it will be set to
127 // true if a new file was created [or an old one truncated to zero length to
128 // simulate a new file, which can happen with PLATFORM_FILE_CREATE_ALWAYS], and
129 // false otherwise. |error| can be NULL.
131 // This function fails with 'access denied' if the |name| contains path
132 // traversal ('..') components.
133 BASE_EXPORT PlatformFile
CreatePlatformFile(const FilePath
& name
,
136 PlatformFileError
* error
);
138 // Same as CreatePlatformFile but allows paths with traversal (like \..\)
139 // components. Use only with extreme care.
140 BASE_EXPORT PlatformFile
CreatePlatformFileUnsafe(const FilePath
& name
,
143 PlatformFileError
* error
);
145 BASE_EXPORT
FILE* FdopenPlatformFile(PlatformFile file
, const char* mode
);
147 // Closes a file handle. Returns |true| on success and |false| otherwise.
148 BASE_EXPORT
bool ClosePlatformFile(PlatformFile file
);
150 // Changes current position in the file to an |offset| relative to an origin
151 // defined by |whence|. Returns the resultant current position in the file
152 // (relative to the start) or -1 in case of error.
153 BASE_EXPORT int64
SeekPlatformFile(PlatformFile file
,
154 PlatformFileWhence whence
,
157 // Reads the given number of bytes (or until EOF is reached) starting with the
158 // given offset. Returns the number of bytes read, or -1 on error. Note that
159 // this function makes a best effort to read all data on all platforms, so it is
160 // not intended for stream oriented files but instead for cases when the normal
161 // expectation is that actually |size| bytes are read unless there is an error.
162 BASE_EXPORT
int ReadPlatformFile(PlatformFile file
, int64 offset
,
163 char* data
, int size
);
165 // Same as above but without seek.
166 BASE_EXPORT
int ReadPlatformFileAtCurrentPos(PlatformFile file
,
167 char* data
, int size
);
169 // Reads the given number of bytes (or until EOF is reached) starting with the
170 // given offset, but does not make any effort to read all data on all platforms.
171 // Returns the number of bytes read, or -1 on error.
172 BASE_EXPORT
int ReadPlatformFileNoBestEffort(PlatformFile file
, int64 offset
,
173 char* data
, int size
);
175 // Same as above but without seek.
176 BASE_EXPORT
int ReadPlatformFileCurPosNoBestEffort(PlatformFile file
,
177 char* data
, int size
);
179 // Writes the given buffer into the file at the given offset, overwritting any
180 // data that was previously there. Returns the number of bytes written, or -1
181 // on error. Note that this function makes a best effort to write all data on
183 // Ignores the offset and writes to the end of the file if the file was opened
184 // with PLATFORM_FILE_APPEND.
185 BASE_EXPORT
int WritePlatformFile(PlatformFile file
, int64 offset
,
186 const char* data
, int size
);
188 // Save as above but without seek.
189 BASE_EXPORT
int WritePlatformFileAtCurrentPos(PlatformFile file
,
190 const char* data
, int size
);
192 // Save as above but does not make any effort to write all data on all
193 // platforms. Returns the number of bytes written, or -1 on error.
194 BASE_EXPORT
int WritePlatformFileCurPosNoBestEffort(PlatformFile file
,
195 const char* data
, int size
);
197 // Truncates the given file to the given length. If |length| is greater than
198 // the current size of the file, the file is extended with zeros. If the file
199 // doesn't exist, |false| is returned.
200 BASE_EXPORT
bool TruncatePlatformFile(PlatformFile file
, int64 length
);
202 // Flushes the buffers of the given file.
203 BASE_EXPORT
bool FlushPlatformFile(PlatformFile file
);
205 // Touches the given file.
206 BASE_EXPORT
bool TouchPlatformFile(PlatformFile file
,
207 const Time
& last_access_time
,
208 const Time
& last_modified_time
);
210 // Returns some information for the given file.
211 BASE_EXPORT
bool GetPlatformFileInfo(PlatformFile file
, PlatformFileInfo
* info
);
213 // Use this class to pass ownership of a PlatformFile to a receiver that may or
214 // may not want to accept it. This class does not own the storage for the
219 // void MaybeProcessFile(PassPlatformFile pass_file) {
221 // PlatformFile file = pass_file.ReleaseValue();
222 // // Now, we are responsible for closing |file|.
226 // void OpenAndMaybeProcessFile(const FilePath& path) {
227 // PlatformFile file = CreatePlatformFile(path, ...);
228 // MaybeProcessFile(PassPlatformFile(&file));
229 // if (file != kInvalidPlatformFileValue)
230 // ClosePlatformFile(file);
233 class BASE_EXPORT PassPlatformFile
{
235 explicit PassPlatformFile(PlatformFile
* value
) : value_(value
) {
238 // Called to retrieve the PlatformFile stored in this object. The caller
239 // gains ownership of the PlatformFile and is now responsible for closing it.
240 // Any subsequent calls to this method will return an invalid PlatformFile.
241 PlatformFile
ReleaseValue() {
242 PlatformFile temp
= *value_
;
243 *value_
= kInvalidPlatformFileValue
;
248 PlatformFile
* value_
;
253 #endif // BASE_PLATFORM_FILE_H_