OLD | NEW |
1 // Copyright 2014 The Crashpad Authors. All rights reserved. | 1 // Copyright 2014 The Crashpad Authors. All rights reserved. |
2 // | 2 // |
3 // Licensed under the Apache License, Version 2.0 (the "License"); | 3 // Licensed under the Apache License, Version 2.0 (the "License"); |
4 // you may not use this file except in compliance with the License. | 4 // you may not use this file except in compliance with the License. |
5 // You may obtain a copy of the License at | 5 // You may obtain a copy of the License at |
6 // | 6 // |
7 // http://www.apache.org/licenses/LICENSE-2.0 | 7 // http://www.apache.org/licenses/LICENSE-2.0 |
8 // | 8 // |
9 // Unless required by applicable law or agreed to in writing, software | 9 // Unless required by applicable law or agreed to in writing, software |
10 // distributed under the License is distributed on an "AS IS" BASIS, | 10 // distributed under the License is distributed on an "AS IS" BASIS, |
(...skipping 60 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
71 | 71 |
72 //! \brief Determines the permissions bits for files created on POSIX systems. | 72 //! \brief Determines the permissions bits for files created on POSIX systems. |
73 enum class FilePermissions : bool { | 73 enum class FilePermissions : bool { |
74 //! \brief Equivalent to `0600`. | 74 //! \brief Equivalent to `0600`. |
75 kOwnerOnly, | 75 kOwnerOnly, |
76 | 76 |
77 //! \brief Equivalent to `0644`. | 77 //! \brief Equivalent to `0644`. |
78 kWorldReadable, | 78 kWorldReadable, |
79 }; | 79 }; |
80 | 80 |
| 81 //! \brief Determines the locking mode that LoggingLockFile() uses. |
| 82 enum class FileLocking : bool { |
| 83 //! \brief Equivalent to `flock()` with `LOCK_SH`. |
| 84 kShared, |
| 85 |
| 86 //! \brief Equivalent to `flock()` with `LOCK_EX`. |
| 87 kExclusive, |
| 88 }; |
| 89 |
81 //! \brief Reads from a file, retrying when interrupted on POSIX or following a | 90 //! \brief Reads from a file, retrying when interrupted on POSIX or following a |
82 //! short read. | 91 //! short read. |
83 //! | 92 //! |
84 //! This function reads into \a buffer, stopping only when \a size bytes have | 93 //! This function reads into \a buffer, stopping only when \a size bytes have |
85 //! been read or when end-of-file has been reached. On Windows, reading from | 94 //! been read or when end-of-file has been reached. On Windows, reading from |
86 //! sockets is not currently supported. | 95 //! sockets is not currently supported. |
87 //! | 96 //! |
88 //! \return The number of bytes read and placed into \a buffer, or `-1` on | 97 //! \return The number of bytes read and placed into \a buffer, or `-1` on |
89 //! error, with `errno` or `GetLastError()` set appropriately. On error, a | 98 //! error, with `errno` or `GetLastError()` set appropriately. On error, a |
90 //! portion of \a file may have been read into \a buffer. | 99 //! portion of \a file may have been read into \a buffer. |
(...skipping 84 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
175 //! | 184 //! |
176 //! \sa ScopedFileHandle | 185 //! \sa ScopedFileHandle |
177 FileHandle LoggingOpenFileForRead(const base::FilePath& path); | 186 FileHandle LoggingOpenFileForRead(const base::FilePath& path); |
178 | 187 |
179 //! \brief Wraps `open()` or `CreateFile()`, creating a file for output. Logs | 188 //! \brief Wraps `open()` or `CreateFile()`, creating a file for output. Logs |
180 //! an error if the operation fails. | 189 //! an error if the operation fails. |
181 //! | 190 //! |
182 //! \a write_mode determines the style (truncate, reuse, etc.) that is used to | 191 //! \a write_mode determines the style (truncate, reuse, etc.) that is used to |
183 //! open the file. On POSIX, \a permissions determines the value that is passed | 192 //! open the file. On POSIX, \a permissions determines the value that is passed |
184 //! as `mode` to `open()`. On Windows, the file is always opened in binary mode | 193 //! as `mode` to `open()`. On Windows, the file is always opened in binary mode |
185 //! (that is, no CRLF translation). | 194 //! (that is, no CRLF translation). On Windows, the file is opened for sharing, |
| 195 //! see LoggingLockFile() and LoggingUnlockFile() to control concurrent access. |
186 //! | 196 //! |
187 //! \return The newly opened FileHandle, or an invalid FileHandle on failure. | 197 //! \return The newly opened FileHandle, or an invalid FileHandle on failure. |
188 //! | 198 //! |
189 //! \sa FileWriteMode | 199 //! \sa FileWriteMode |
190 //! \sa FilePermissions | 200 //! \sa FilePermissions |
191 //! \sa ScopedFileHandle | 201 //! \sa ScopedFileHandle |
192 FileHandle LoggingOpenFileForWrite(const base::FilePath& path, | 202 FileHandle LoggingOpenFileForWrite(const base::FilePath& path, |
193 FileWriteMode write_mode, | 203 FileWriteMode write_mode, |
194 FilePermissions permissions); | 204 FilePermissions permissions); |
195 | 205 |
| 206 //! \brief Locks the given \a file using `flock()` on POSIX or `LockFileEx()` on |
| 207 //! Windows. |
| 208 //! |
| 209 //! It is an error to attempt to lock a file in a different mode when it is |
| 210 //! already locked. This call will block until the lock is acquired. The |
| 211 //! entire file is locked. |
| 212 //! |
| 213 //! If \a locking is FileLocking::kShared, \a file must have been opened for |
| 214 //! reading, and if it's FileLocking::kExclusive, \a file must have been opened |
| 215 //! for writing. |
| 216 //! |
| 217 //! \param[in] file The open file handle to be locked. |
| 218 //! \param[in] locking Controls whether the lock is a shared reader lock, or an |
| 219 //! exclusive writer lock. |
| 220 //! |
| 221 //! \return `true` on success, or `false` and a message will be logged. |
| 222 bool LoggingLockFile(FileHandle file, FileLocking locking); |
| 223 |
| 224 //! \brief Unlocks a file previously locked with LoggingLockFile(). |
| 225 //! |
| 226 //! It is an error to attempt to unlock a file that was not previously locked. |
| 227 //! A previously-locked file should be unlocked before closing the file handle, |
| 228 //! otherwise on some OSs the lock may not be released immediately. |
| 229 //! |
| 230 //! \param[in] file The open locked file handle to be unlocked. |
| 231 //! |
| 232 //! \return `true` on success, or `false` and a message will be logged. |
| 233 bool LoggingUnlockFile(FileHandle file); |
| 234 |
196 //! \brief Wraps `lseek()` or `SetFilePointerEx()`. Logs an error if the | 235 //! \brief Wraps `lseek()` or `SetFilePointerEx()`. Logs an error if the |
197 //! operation fails. | 236 //! operation fails. |
198 //! | 237 //! |
199 //! Repositions the offset of the open \a file to the specified \a offset, | 238 //! Repositions the offset of the open \a file to the specified \a offset, |
200 //! relative to \a whence. \a whence must be one of `SEEK_SET`, `SEEK_CUR`, or | 239 //! relative to \a whence. \a whence must be one of `SEEK_SET`, `SEEK_CUR`, or |
201 //! `SEEK_END`, and is interpreted in the usual way. | 240 //! `SEEK_END`, and is interpreted in the usual way. |
202 //! | 241 //! |
203 //! \return The resulting offset in bytes from the beginning of the file, or | 242 //! \return The resulting offset in bytes from the beginning of the file, or |
204 //! `-1` on failure. | 243 //! `-1` on failure. |
205 FileOffset LoggingSeekFile(FileHandle file, FileOffset offset, int whence); | 244 FileOffset LoggingSeekFile(FileHandle file, FileOffset offset, int whence); |
206 | 245 |
207 //! \brief Wraps `close()` or `CloseHandle()`, logging an error if the operation | 246 //! \brief Wraps `close()` or `CloseHandle()`, logging an error if the operation |
208 //! fails. | 247 //! fails. |
209 //! | 248 //! |
210 //! \return On success, `true` is returned. On failure, an error is logged and | 249 //! \return On success, `true` is returned. On failure, an error is logged and |
211 //! `false` is returned. | 250 //! `false` is returned. |
212 bool LoggingCloseFile(FileHandle file); | 251 bool LoggingCloseFile(FileHandle file); |
213 | 252 |
214 //! \brief Wraps `close()` or `CloseHandle()`, ensuring that it succeeds. | 253 //! \brief Wraps `close()` or `CloseHandle()`, ensuring that it succeeds. |
215 //! | 254 //! |
216 //! If the underlying function fails, this function causes execution to | 255 //! If the underlying function fails, this function causes execution to |
217 //! terminate without returning. | 256 //! terminate without returning. |
218 void CheckedCloseFile(FileHandle file); | 257 void CheckedCloseFile(FileHandle file); |
219 | 258 |
220 } // namespace crashpad | 259 } // namespace crashpad |
221 | 260 |
222 #endif // CRASHPAD_UTIL_FILE_FILE_IO_H_ | 261 #endif // CRASHPAD_UTIL_FILE_FILE_IO_H_ |
OLD | NEW |